Full text of "QNX 2.2 Reference Guide"

See other formats

Version 22

Operating System

Version 2.2x

QNX Software Systems, Ltd.

QNX Software Systems Ltd.

175 Terence Matthews Crescent
Kanata, Ontario K2M 1W8
Canada
613-591-0931

No part of this publication may be reproduced, stored in a retrieval system, or
transmitted in any form or by any means, electronic, mechanical photocopying,
recording, or otherwise without the prior written permission of QNX Software
Systems Ltd.

Although every precaution has been taken in the preparation of this book, we
assume no responsibility for any errors or omissions, nor do we assume liability for
damages resulting from the use of the information eomamc-u m tm?. uo-uk.

Printing history:

May 1993 First edition

March 1994 Reprint

September 1994 Reprint

QNX and the <§> symbol are registered trademarks of QNX Software Systems Ltd.
All other trademarks or registered trademarks belong to their respective owners.

Printed in Canada.

(X) 1200-03

QNX Manual

Page

1. Introduction 1

1.1 What You Were Shipped 1

1.2 Booting QNX 3

2. Installation Using The Install Command s

3. Manual Installation i

3.1 Background on Disks and disk drivers 7

3.1.1 XT Hard Disk Driver 9

3.1.2 AT Hard Disk Driver 10

3.1.3 PS2 Hard Disk Drivers (model 50 and up) 10

3.1.4 HP NIGHTHAWK Hard Disk Driver 11

3.1.5 BIOS Hard Disk Driver 11

3.2 Step-by-step Installation of Hard Disk 12

3.3 Creating A System Initialization File 20

3.4 Summary 22

3.5 Creating A Login Password File 23

3.6 Mounting a DOS or Second QNX Partition 26

3.7 More than One Physical Hard Disk 27

3.8 Changing Operating System Defaults 27

3.9 Removing the QNX loader 28

4. Network Installation 29

4.1 Hardware Installation 29

4.2 Software Installation 29

4.3 Summary 32

4.4 Starting the Poller 32

4.5 Recovery Without the Poller 33

4.6 Troubleshooting QNET Network Installation 34

4.6.1 Diagnostic Tips 35

4.6.2 Symptom Checklist 35

5. Terminals, Modems and Printers 37

5.1 Serial 37

5.1.1 I/O ports and Interrupts 37

5.1.2 Baud Rates and Parity 38

5.1.3 Connecting Cables (DTE vs DCE) 39

5.1.4 Setting QNX Line Editing Options 41

5.1.5 Flow Control 41

5.1.6 Logging In From A Terminal 42

5.1.7

Logging In From A Modem

5.2

Outgoing Calls

5.2.1

Problems

5.3

Parallel

5.4

Smartcards

6 . Devices

6.1

Terminal Input

6.1.1

Alt, Shift and Ctrl

6.1.2

Caps Lock, Num Lock

6.1.3

Type-Ahead

6.1.4

Line Editing

6.1.5

Compose Characters

6.1.6

Input Gate

6.1.7

Recalling Command Lines

6.2

Terminal Output

6.2.1

Attributes

6.2.2

Output Escape Sequences

7. Full Screen Consoles

' 55

7.1

Mounting Consoles

7.2

Switching Consoles

7.3

Initiating Commands in Other Consoles

7.4

Consoles and Graphics

8 . Files

8.1

File Names

8.2

Structure of Files

8.3

Directories

8.4

Pathnames

8.4.1

Specifying a Drive as Part of Your Pathname

8.5

Your Current Directory

8.5.1

Changing Your Current Directory

8.6

Moving Up the File Structure

8.7

File Attributes and Permissions

8.8

User Numbers

8.9

Device Names

8.10

Network Access to Files and Devices

8.10.1

Remote Search Order

8.10.2

Automatic Remote Searching

8.10.3

Remote Current Directory

8.10.4

Mounting A Remote Disk

8.10.5

Network Devices

8.10.6 Limiting Network Access 78

9. The Command Interpreter (Shell) 79

9.1 Shell Prompt 79

9.2 Command Input/Output Redirection 80

9.3 Quoting 81

9.4 Filename Generation 82

9.5 Querying ' 83

9.6 Background Tasks 83

9.7 Multiple Commands On a Line 84

9.8 Pipes 84

9.9 Comment Lines 85

9.10 Executing Commands on Another Node 85

9.11 Command Files 86

9.11.1 Built-In Shell Variables 86

9.11.2 User Shell Variables 87

9.11.3 Executing Shell Commands 88

9.12 Local Shell Commands 89

9.13 Quick Reference to the Shell 90

10. Tasks 93

10.1 Introduction 93

10.2 System Tasks 94

10.3 Inter-task Communication 95

10.3.1 Messages 96

10.3.1a Death of a Task 99

10.3.1b Messages Across the Network 99

10.3.1c Virtual Circuits 100

10.3.2 Ports 100

10.3.2a Identification - single node only 101

10.3.2b Semaphores 102

10.3.2c Signals 102

10.3.3 Exceptions 103

10.4 Global Names 106

10.5 Task States 106

10.6 Task Ids 108

10.7 Task Hierarchy 108

10.8 Task Creation 109

10.9 Terminal Ownership 109

11. QUICS - The QNX Update System m

11.1 How To Phone Us 112

11.2 X25 Access 113

iii

12 , Tips on Using QNX ns

12.1 Memory Requirements 115

12.2 Enabling Colour 115

12.3 Disabling Colour 115

12.4 The Mount Command 115

12.5 Ramdisk 117

12.6 Shared Libraries 118

12.7 Operating On Groups Of Files 118

Character Set and Keyboard Codes 119

1. Introduction

BE SMART AND READ THIS

This chapter is written for the first time QNX user who wishes to install QNX on
an IBM PC, AT, HP Vectra, PS/2 or compatible. The documentation will take you
step by step through the installation procedure. If you run into problems not
covered by the manual you may call the QNX technical support line.

Technical Support

(613) 591-0941 (9:30 am to 5:30 pm EST)

The installation involves the execution of a number of QNX utility commands.
Over time you will become familiar with these commands but right now we will
only cover the basics needed to get started. Although you can execute the com-
mands directly, we have provided an install program which will invoke the neces¬
sary commands from a user friendly menu.

It is your choice whether to install the system manually or through the install
command. Both are documented below (With Install - chapter 2, Manually -
chapter 3), however the manual method contains much more technical detail. This
detail is usually appreciated by the technical user and may be overpowering for the
novice. We recommend that you use the install program and read through the
manual installation which parallels the execution of the program. In any case, the
first step is to read the rest of this chapter.

If you are upgrading DO NOT use the INSTALL
command. It will destroy your existing QNX files.

Use the documentation provided with your upgrade.

1.1 What You Were Shipped

QNX is provided on several floppy diskettes. Depending on the configuration you
have ordered, you will have received some (or all) of the following diskettes:

360K Diskettes

Disk Directories Contents

1 QNX 22x Boot

/cmds Essential commands

/netboot Operating system images

QNX Introduction

QNX 1

2 QNX 2.2jc loot Utilities

/cmds

/eonfig

/drivers

/expl

3 Utilities 1

/cmds

4 Utilities 2

/cmds

5 "C"-Compiler 1

/cmds

/samples

6 "€ ,? Compiler ?-

/lib

/mathlib

/mathlib8087

Other commands
Configuration files
Disk and graphics drivers
Explain files

Utility commands

Compiler, Assembler
and Linker...

Some C programs

System library
Floating point library
8087 floating point library

720K/1.2Meg Diskettes

Disk Directories

1 QNX 2.2x Boot

/cmds

/netboot

/eonfig

/drivers

/expl

/user/qnx

2 Utilities

/cmds

3 "C” Compiler

/cmds

/lib

/mathlib

/mathlib8087

/samples

Contents

Commands

Operating system images
Configuration files
Disk and graphics drivers
Explain files
User directory

Utility commands

Compiler, Assembler
and Linker...

System library
Floating point library
8087 floating point library
Some C programs

QNX 2

Introduction

We always ship two versions of QNX. One which runs in real mode on PC’s,

AT’s and PS/2’s and one which runs in protected mode on AT’s and PS/2’s. There
is also a special version for old style HP Vectras (earlier than Oct 87). You must
request the special Vectra version. The standard processor types are:

PCAT - PC* AT, VECTRA, PS/2 or compatible running in real mode.

ATP - AT, VECTRA, PS/2 or compatible running in protected mode.

HV - Early HP Vectra running in real mode.

HVP - Early HP Vectra running in protected mode.

The PCAT and HV boot ran in real mode (like DOS) and limits you to 640K of
memory. The ATP and HVP boot ran in protected mode and allow up to 15
Megabytes of memory.

The same QNX utilities and applications will work on ALL of these versions of
QNX. Also, any application developed by yourself or others should work equally
well on each QNX version. The operating system is responsible for providing this
machine independence.

1.2 Booting QNX

To boot QNX, place the disk labeled "QNX 22x Boot" in drive 1 and turn on the
main power switch of your Personal Computer. If power was already switched on,
turn it off for at least 10 seconds then turn it back on.

On a PC, QNX will prompt you for today’s date. You should enter it in the form
indicated by the prompt. For example, you could set the date and time to 12 Oc¬
tober 1987 at 2:34 in die afternoon by typing:

12 oct 87 2 34 pm

On an AT or PS/2 the date will be read from the built-in clock/calendar.

QNX will now prompt you to login with the following message:

QNX Version 22% Release x node n

Logim

QNX Introduction

QNX 3

You should enter qnx followed by a carriage return at this point

which will log you in as a super-user. The dollar sign ($) prompt indicates that
QNX is waiting for a command. You will now have to configure QNX for your
machine. If you have received a networked version of QNX, you should first
configure a single machine. After you have gained experience with it, you may
then configure the other machines in the network. These other machines will boot
over the network. This is explained in more detail later on.

You should now go to chapter 2 (install program) or chapter 3 (manual instal¬
lation).

QNX 4

Introduction

2. Installation Using The Install Command

Do not read on until you have read chapter 1.

If you are upgrading DO NOT use the INSTALL
command. It will destroy your existing QNX files.

Use the documentation provided with your upgrade.

This install program should cover 95% of all installations. The program does not
perform the installation itself but invokes a set of standard QNX utility commands
to perform each step. These steps are described in more detail in chapter 3 which
parallels the execution of the install program. You do not need to read it unless
you want more detail on what is going on. This way you will learn a bit about
QNX during the installation. Each utility is described in detail in the Utilities area
of the manual (Utilities Tab).

At this point you should have booted QNX and have logged in as described in
section 1.2. If you have booted from a 360K boot diskette, replace it with the boot
utilities diskette. Then at the dollar sign prompt type the command

$ install

and simply answer the questions presented to you. If you wish to install QNX on
more than one hard disk partition or on more than one hard disk in the same
machine you will have to read chapter 3. In this case you may still use the install
program to create your first QNX partition on your first hard disk.

If you wish to share you disk with DOS
we recommend that you install DOS first
leaving room on the hard disk for QNX.

QNX Menu-Driven Installation

QNX 5

QWX 6

Menu-Driven Installation

Do not read on until you have read chapter 1.

This section describes in detail how to install QNX. If you consider yourself to be
a novice you should probably refer to chapter 2 for a menu-driven installation.
Even experienced users will like INSTALL.

The information in this section is useful and worth reading even if you do opt for
the menu driven install program. Each utility command involved is described in
greater detail in the Utilities area of the manual (Utilities Tab).

Controller

Disk -2 (H2,T2,M2)

.. cables

Disk 1

(Hi / Ti,Ni)

Bus

Disk drives are available in various sizes. QNX needs to know the following in¬
formation about a drive:

Number of heads

Number of tracks on each platter

Number of sectors on each track

The total size of the disk will be:

Total number of blocks is
Total number of bytes is

H*T*N
H*T*N * 512

Depending on the disk controller, one or more disk drives may be connected to it.

For QNX to communicate with a hard disk, an interface module called a driver
must be properly mounted into the operating system. A driver is specific to a par¬
ticular disk controller and knows the following information about that controller:.

■» I/O registers

- DMA Channels used

- Interrupt used

QNX Manual Installation

QNX 7

The MOUNT utility command is used to mount a driver. Each driver assumes a
default value for the number of tracks, heads and sectors on your disk. For ex¬
ample, the XT driver assumes a 10 Meg disk while the AT driver uses the disk type
defined by your AT setup program to determine the size of the disk. If you have a
non-standard disk, the values for h, t and n can be overridden when you mount the
driver.

The number of heads and tracks should be provided by the vendor when you
receive your hard disk. Most drives contain 17 sectors per track. If you have an
RLL drive it may contain 25 sectors per track. If you have an ESDI drive it may
contain 34 or 35 sectors per track, although some ESDI controllers , for com¬
patibility, pretend they have 17 sectors/track but twice the number of heads.

A driver treats each drive as a consecutive series of physical 512 byte blocks,
starting at one and continuing to some number which is determined by the capacity
of the drive (H*T*N). The drivers will normally map blocks through sectors,
heads and then tracks with increasing block numbers. This minimizes head
movement.

Here is a partial syntax of the MOUNT command regarding hard disks. Further
information on this command can be found in the Utilities manual.

mount disk drive Idrivers/driverjtame pa =osjype

h =heads t=tracks n-sectors! track

NOTE: IF YOU MUST SPECIFY H, T or N YOU MUST SPECIFY ALL
THREE PARAMETERS

In this command you have indicated 4 separate pieces of information. -

drive - The number of the drive from QNX’s point

of view. QNX allows drive numbers from
1 to 8. Note that unlike DOS which uses
letters for drives, QNX uses numbers. Although
you may choose your own drive numbers, we
recommend you adopt the following scheme:

Disk Use
1. Floppy 1
2 ' Floppy 2 if present

continued...

QNX 8

Manual Installation

3 Hard disk QNX partition #1

4 Hard disk partition #2

5 Ramdisk

driver_name - This identifies the software driver for a

particular controller, (xt, at,...).

h, t and n - The physical structure of the hard disk. If
these parameters are omitted, the driver will
■ assume a default which may or may not be
correct. Please refer to the documentation
on each driver.

osjype - The name of the partition to use. This may be

the name qnx, qny, qnz, dos, or a number.

Type Description

qnx QNX partition (same as number 7)

qny QNX partition (same as number 8)

qnz QNX partition (same as number 9)

dos DOS 2.1 partition (same as number 1)

1 ... 255 An explicit operating system osjype

When MOUNTING it is not necessary to specify the three key parameters of H, T
and N unless the driver is unable to determine them. The capabilities of each
driver we supply are described below.

3.1.1 XT Hard Disk Driver

A large number of drives now on the market boast an XT compatible hard disk
controller. This controller must be compatible at the physical hardware level.
Compatibility at the BIOS (ROM) level is not enough to use this driver. This
driver assumes the old 10 Meg disk shipped by IBM on their old XT. If you have a
20 meg disk or one which is not identical to the default you must specify the
proper number of tracks, heads and sectors.

QNX Manual Installation

QNX 9

<--Default

Heads Tracks Sectors SIZE

XT 4 306 17 10M

mount disk 3 /drivers/disk a xt

Other 2 612 17 10M

mount disk 3 /drivers/disk,xt t=612 h=2 n=17

Other 4 612 17 20M

mount disk 3 /drivers/disk.xt t=612 h=4 n=17

3.1.2 AT Hard Disk Driver

The AT driver uses the disk parameter table setup by the BIOS to determine the
size of the disk. ■ This means that you should NOT have to specify H, T or N when
mounting the AT driver UNLESS you are using a drive other than that shipped by
the AT manufacturer AND which does not correspond to any of the manufacturers’
disk types as defined by the AT SETUP program.

You would mount the AT driver as follows. The second example is for a drive
which the does not have a supported disk type in the AT setup program provided
with your machine. If you are using an unsupported drive, you must specify the
number of tracks, heads and sectors.

mount disk 3 /drivers/disk a at

mount disk 3 /drivers/disk.at t -tracks beheads n -sectors

3.1.3 PS2 Hard Disk Drivers

The PS/2 driver(s) use the disk parameter table setup by the BIOS to determine the
size of the disk. This means that you should NOT have to specify H, T or N when
mounting the PS/2 driver.

The model 25 and 30 use the driver in the system BIOS.

Model 25 9 30

mount disk 3 /drivers/diskJbios

There are two controllers available for the PS/2 models 50 and up. One interfaces
to an ST506 type drive and one to an ESDI drive. The ESDI controller is not cur¬
rently available for the model 50. These are high performance drivers which fea¬
ture read-ahead and write-behind. You should read the technical note "Page

QNX10

Manual Installation

Caching Disk Drivers" in the technical notes section.

Mode! 50 and tip

ST506 Drive

mount disk 3 /drivers/disk.ps2 read technical note

ESDI Drive (disks > 70 Megabyte)

mount disk 3 /drivers/disk.ps2esdi read technical note

3.1.4 HP NIGHTHAWK Hard Disk Driver

When you purchase an HP vectra there is an optional hard disk and controller
available for it. It is usually sold into process control markets and at this printing it
had a part number of 45816A. Within HP, it is sometimes referred to as die
"Nighthawk" hard disk controller.

You would mount the driver as follows.

mount disk 3 /drivers/disk.nighthawk

3.1.5 BIOS Hard Disk Driver

This driver uses the INT13 BIOS calls to perform hard disk I/O and will only
work in REAL MODE versions of QNX. It will work on any controller card or
machine which supports INTI3 hard disk I/O. These cards usually contain a ROM
which the BIOS finds and executes when power is turned on. This allows us to
provide immediate support for the many new drives on the market. The BIOS
driver reads the disk configuration table set up by the BIOS to determine the
physical characteristics of the hard disk. This can be over-ridden (if required) by
specifying tracks, heads and sectors on the mount command. This driver should
only be used as a last resort.

This is a busy-wait driver and may cause a slight stutter effect in a multi-user en¬
vironment. The BIOS driver will not work in protected versions of QNX (ATP)
nor can it be used with the DOS emulator.

mount disk 3 /drivers/diskJbios
or

mount disk 3 /drivers/diskJbios t-tracks h-heads n=sectors

QNX Manual Installation

QNX 11

3.2 Step-by-step Installation of Hard Disk

At this point you should have booted QNX and have logged in as described in
section 1.2. The procedure required to install QNX onto your hard disk is de¬
scribed here in a step-by-step fashion.

NOTE that any QNX command will print a short usage message when a ’?’ is
specified as the only command line argument. If you wish to know more about the
commands, please refer to the "Utilities" manual.

111 Creating a QNX hard disk partition

To create a hard disk partition on your disk, you must use the commands outlined
below with the proper arguments.

f..’.:.~~~~ Step la - Mounting a Hard Disk Driver _ .

QNX supplies a number of drivers for hard disks under the directory ’/drivers’ on
your boot diskette. The following drivers are provided:

File Name Description

/drivers/disk.xt XT hard disk driver

/drivers/disk.at AT hard disk driver

/drivers/disk.bios BIOS hard disk driver

/drivers/disk.eighthawk Hewlett-Packard nighthawk hard disk driver

A standard HP Vectra uses the AT driver
/drivers/disk.ps2 PS2 ST506 hard disk driver

/drivers/disk.ps2esdi PS2 ESDI hard disk driver

Once you have decided on the appropriate driver file, you must mount it into the
system using the MOUNT command. Until the driver is mounted you will be
unable to access your hard disk.

At this point you should mount the hard disk as one large volume. Once the
driver is loaded you will be able to read and write to block 1 of the disk which
contains the partition information. You will then use FDISK to set up a QNX
partition and immediately remount the driver specifying that it constrain itself to
block accesses within the created partition. Some examples follow:

QNX 12

Manual Installation

XT with standard Id Meg disk (default)
mount disk 3 /drivers/disk.xt

XT with 2d Meg Seagate ST255 disk

mount disk 3 /drivers/disk.xt h=4 n=17 t=612

AT with standard 2d Meg disk (disk type 2)
mount disk 3 /drivers/disk.at

AT with nonstandard 6d Meg disk (disk type unknown)
mount disk 3 /drivers/disk.at h=7 n=17 t=98d

In the last example the user has installed a disk drive which does not match any of
the defined disk types known by the AT SETUP command.

I ; . ' Step 1b .- Partitioning' Your Hard .Disk.

You will now have to partition all or part of your hard disk for the exclusive use of
QNX. Partitioning allows different operating systems to share a single hard disk
without conflicting with each other.

You should now run the FDISK command to set up a QNX partition on the newly
mounted disk.

fdisk 3

Look at the bottom of your screen and verify that the size of your disk and the
values for H=, T= and N= are reasonable. If they do not reflect what you believe
to be the size of your disk, then either the disk type is incorrect (AT, PS/2), the
default values are incorrect (XT) or the wrong values for h, t and n were provided
to the MOUNT command.

There are 4 partition slots. Use the up/down cursor keys to select one that is not in
use. Type the letter c to select the change option. You should now enter the OS
type (7 for QNX) and the start and end,cylinder to be used for the QNX partition.
Enter a carriage return after entering each number. The QNX partition may be any
size up to 1 terabyte which easily covers all disks on the market today.

If other partitions already exist, your QNX partition must NOT overlap them. If
the DOS partition takes up the entire drive you will have to reboot DOS, backup all
your DOS files and reduce the size of the DOS partition before creating a QNX
partition. If there is room for a QNX partition, then after you have made your

QNX Manual Installation

QNX 13

changes you must type s to save them back to the disk. Then type q to quit. Hie
following is a typically partitioned hard disk as seen in FDISK.

Ignore Next Prev Change Delete Mount Boot Unboot Save Quit

OS start End Number Boot

Cylinder Cylinder Cylinders Blocks

1. dos { 1 ) 1 350 350 23867

—> 2. qnx ( 1 ) 351 612 262 17816 *

Use up/down arrows to select partition.

Type the letter ,c to change/add a partition.

Type the letter s to save your changes.

Type ■the letter q to quit.

QNX is os type 7,8 or 9 DOS is os type 1 or 4 Unused is os type 0

First cylinder is 0 Last cylinder is 614
Disk is 21,411,840 bytes T=615 H=4 N=17

Step 1c - Remount Disk to use the QNX Partition

Now that you have created a QNX partition you MUST re-issue the mount for
drive 3, to restrict it to the new partition. This time we will not specify a driver, but
use the d -driver jium option to tell mount to use the same driver as it is currently
using for drive 3. For example:

mount disk 3 d=3 pa=qnx

mount disk 3 d=3 t=612 h=4 n=17 pa=qex

You now have a fully functional disk driver mounted and can set up a QNX file
structure.

QNX 14

Manual Installation

This MOUNT with the d =drive_num and the previous MOUNT and FDISK com¬
mands need only be done this one time to set things up. From now on, each time
you boot QNX you will have to mount the disk driver with the pa=qnx option and
if necessary the h=, t= and n= options. For example:

mount disk 3 /drivers/disk.at pa=qnx

mount disk 3 /drivers/disk.xt t=612 h=4 n=17 pa=qnx

You will be shown a little later how to place this mount command in a system
initialization file which is automatically executed each time you boot.

Step Id - Format QNX partition (AT’s only)

Unless you have mounted /drivers/disk.at you should skip this step.

Users installing QNX on an AT may gain a significant performance increase by
reformatting the QNX partition with a different interleave than that used by DOS.
This step is optional but highly recommended. Use the FDFORMAT utility with
the +hard option to reformat the QNX partition.

fdformat 3 +hard - Format partition for drive 3 with
the default interleave (s=6).

If you have a very fast machine (16 MHz 386) then you may wish to format with a

smaller interleave (also called stagger).

fdformat 3 +hard s=5 - Format partition for drive 3 with

an interleave of 5.

If you attempt to format a non-AT hard disk you will receive errors and the disk
should not be affected.

QNX Manual Installation

QNX 15

Initializing the QNX File Structure

To Initialize the file structure for your disk, you must use the commands outlined
below with the proper arguments.

Step 2a - Create a QNX File System

Before you can use your QNX partition you must create an empty QNX file system
on it. This is done with the DINIT command. The command takes the drive
number of the disk and a flag to indicate that it is a hard disk. Type the following
command:

dinit 3 +hard

The DINIT command is also used to initialize the file system on floppy diskettes

__ j *11 ^ ^ 14 ^ nnu 0 .

dliil JL uu will UiClWlWiC UL&v tlllo WMAlMiiciliHj. lilciiiy tliliCo. 1 liC 41

option is necessary only when initializing a hard disk and protects you should you
accidentally type in the wrong drive number when initializing a floppy.

Step 2b - Mark Tracks You know are Bad

If your hard disk was shipped with a sheet of paper containing a list of bad tracks
then you may use the DMARK command to explicitly mark the blocks on these
tracks as un-usable. If you are willing to trust the DCHECK command to find all
bad blocks you may skip this step. (On occasion, where blocks are intermittently
bad, DCHECK may miss them). The DMARK command takes a list of tracks and
heads. Each pair is separated by a space and the track and head are separated by a
comma. For example:

dmark 40,4 250,2 500,0 >3:/badJblks - mark track 40 head 4

250 2

500 0

We have redirected its output to 3:/bad blks so that it can be used with the

DCHECK utility.

Note that even if only a single block is bad, the entire track is sacrificed. This is
because interleaving of sectors on the disk locates blocks in different places,
beyond our control.

QNX 16

Manual Installation

You should now check for bad blocks in your QNX partition. The DCHECK
command will attempt to read every block and will report any bad blocks it
discovers. We will invoke it with the +mark option which will set these blocks as
un-usable in the hard disk’s allocation bitmap.

DCHECK will also look for /badblks file on the specified drive. If there is one,
any block numbers it contains will be marked as un-usable in the bitmap. Any bad
blocks it has found during its reading of the disk are added to the /bad blks file.
Type the following command:

dcheck 3 +mark

This command may take a while on large disks.

Copy Files from Floppies to Hard Disk

To transfer the files from the floppies you have received to your hard disk, you
must use the commands outlined below with the proper arguments.

Step 3a - Copy Files From Boot Flo

You are now ready to copy the QNX files from your floppy diskettes to your hard
disk. This is done with the BACKUP utility command which copies files and
directories from one location to another. It takes as arguments, the source direc¬
tory and the destination directory, followed by options. Place the disk labeled
QNX Boot in drive 1 and type the following command:

backup 1:/ 3:/ +all s=c

I L Suppress clearing the modify bit.

L Copy all files.

L Destination is root directory on hard disk.

L Source is root directory on floppy diskette.

Step 3b - Take Commands From Hard Disk

QNX Manual Installation

QNX 17

You now have enough commands on the hard disk to switch over to it. This is
done with the SEARCH command which tells QNX which drives to search when
looking for commands. Currently your search order is 1 (single floppy) or 1 2 (two
floppies). Type the following command:

search 3

Step 3c - Copy Other Floppies to Hard Disk

You should now copy the files on your other floppy diskettes to the hard disk.

Type the following command for each floppy diskette you received.

backup lit 3:1 +all s=c - utilities diskette

backup til 3:1 +all s=c - c compiler diskette

... etc*

The backup command is the easiest way to move the files on any diskette you
receive from QNX Software Systems Ltd. to your hard disk. Pressing the up-arrow
key recalls the last line and allows you to easily issue multiple BACKUP com¬
mands.

Makinq QNX Boot From Hard Disk

The following describe the steps you will need to take to get a QNX hard disk
partition to boot from hard disk.

Step 4a - Set OS imaae file to boot

You will need to use the BOOT command to enable hard disk booting. Its syntax
is of the form:

boot os_file_name lc=config_Jile] [d=disk_driver] [-pause] [+qnxloader]

QNX 18

Manual Installation

osJilejname

If you have properly backed up the floppies, you now have at least two OS
image files (osjilejiame) under the /netboot directory on your disk. One is
os.2.10pcat (REAL MODE), the other is os.2.10atp (PROTECTED MODE).
If you have the special HP Vectra version, they will be os.2.10hv and
os.2.10hvp. One of these needs to be specified as the first argument to the
BOOT command. This mechanism allows you to easily change whether you
want to boot real or protected mode. It is also handy if you download a beta
version of an OS from QUICS, our online update system, and wish to try it
out.

[c=conflg_file] and [-pause]

These are not described here. See the section called "Changing Operating
System Defaults", as well as the "Utilities" manual for more details.

[d=disk_driver]

When QNX boots, it needs a hard disk driver in order to access the hard disk.
Unlike DOS, it cannot use the BIOS driver which does not work in protected
mode. You must specify which hard disk driver to bind into a hard disk boot.
The d^diskjdriver option creates a file called /config/hdisk.cfg which is
loaded in from hard disk along with the operating system file osjilejiame.

[+qnx!oader]

To boot QNX you must create a hard disk boot loader. You have two choices.
You can use the default loader used by DOS or you can use a special QNX
loader. The former will always boot the active partition as set by the QNX or
DOS FDISK program. The latter will default to the active partition ( which
can be DOS ) but will pause for several seconds and allow you to override it
with another partition number which you may specify by typing in a single
digit from 1 to 4. This gives more flexibility. However, if you have non¬
standard hardware or are already using a special loader then the QNX loader
may cause you problems. For 99.9% of all installations we recommend you
use the QNX loader.

IF YOU DO NOT HAVE A BOOTABLE DOS PARTITION
YOU SHOULD SPECIFY THE QNX LOADER

You need only specify the d=disk__driver and +qnxloader options the first time
you configure for hard disk booting. Later, if you wish to boot a different operating
system (OS), simply specify the osjilejiame argument to the BOOT command
and nothing else. Here are some examples:

1) Boot real mode on an XT, using the DOS loader,
boot /netboot/os.2.10pcat d=/drivers/disk.xt

QNX Manual Installation

QNX 19

2) Boot protected mode on an AT, using the QNX loader.

boot /netboot/os.2.10atp d=/drivers/disk.at +qnxloader

3) Specify a different OS to boot, leave the driver and loader intact.

boot /netboot/testos

NOTE*. Regarding the /netboot/os Jllejname and /config/hdisk.cfg files, you
may copy a new file on top of them but NEVER remove them (FREE, RM,...) and
then create a new one even if they have the same name. The BOOT command
saves away the absolute start blocks of each of these files which will change once
the file is removed. The BOOT command will always reset the proper starting
block.

Step 4b - Make partition bootable

Your last step is to make the QNX partition the active, bootable partition. Type in
the FDISK 3 command again, use the arrow keys to point to the QNX partition and
type the letter ! b’ for boot,(this will put a under the "boot" heading ), the letter

Y for save and finally the letter ’q’ to quit.

fdisk 3

Select QNX with upldown arrows
Type the letter b
Type the letter s
Type the letter q

Make bootable.
Save.

Quit.

You should now be able to boot from hard disk. Open the door to your floppy and
simultaneously press the following 4 keys:

CTRL ALT SHIFT DEL

3.3 Creating A System Initialization File

Each time QNX is booted it will execute the commands in a file called

/config/sys.init.iwwn - Specific to node nnnn, initial choice.

/config/sys.init - Default.

where nnnn is the node number of the node which is booting (if you do not have a
networking card, QNX will look for "sys.init.O" ). If that file does not exist then it
will try /config/sys.init (no node postfix).

QNX 20

Manual Installation

config

i-1- 1 — - 1 -:- 1

sys.init sys .init. 0 sys .init. 1 sys .init. 3

default

The message which greets you each time you log in is currently in the sys.init file.
As you become acquainted with QNX, you will probably wish to add commands to
this file which will customize QNX to your needs. This file typically contains
commands to mount special disk drivers, set terminal options and perhaps read the
date from a clock/calendar card. We will quickly illustrate a typical system
initialization file. These files can be created, and may be modified with the editor
(ED). You may want to refer to the section called ’’Tips on Using QNX' 1 .

rtc at Set QNX’s date. ( AT*s only )

mount bmcache d=3 Mount a bitmap cache

mount cache d=3 s=32k Mount a directory cache

mount xcache s=4k Mount an extent header cache

mount float Mount a floating point library

mount lib /drivers/glib.ega Mount graphics and 43 line console

library

mount console $con2 Mount a second virtual console

cp /expl/logo $con Print QNX logo

clock a=fl04 & Put a clock in top right corner

QNX Manual Installation

QNX 21

3.4 Summary

The following chart summarizes the steps necessary to install QNX on an AT hard
disk.

| Mount the driver as disk 3

mount disk 3 /drivers/disk.at
Create a QNX partition

fiisk 3

Re-mount the QNX partition

mount disk 3 d=3 pa=qnx

Format QNX partition (AT’s only)
fdformat 3 +hard
Initialize the hard disk
dinit 3 +hard

| Check and mark bad blocks

dmark 3 track Jiead >3:/badJbIks
dcheck 3 +mark

Backup the contents of your BOOT floppy
backup hi 3:/ +all s=c BOOT disk in drive 1
Change your search order
search 3

| Backup the remaining diskettes

backup hi 3:1 -4-all s=c Repeat for each floppy

| Set OS image file to boot and hard disk driver to use

QNX 22

Manual Installation

boot 3:lmtbootlosname d=/driver s/disk.at

| Make ONX partition bootable

fdisk 3

3.5 Creating A Login Password File

QNX has the capability of supporting more than one user at a time, many of which
may be located at remotely attached terminals. For this reason you may wish to
restrict access to the system and its files by creating a file of allowable userids and
passwords. This capability is activated by the command

"passon"

NOTE: Passwords are automatically turned on when a machine is booted from
the network. This means you will have to create a password file if you are booting
from the network.

After prompting for the login and password

QNX attempts to open the file "/config/pass". If it does not exist then access will
be denied.

Users are identified by a userid and a group and member number which determines
their permissions. QNX supports up to 256 groups each with a maximum of 256
user numbers ranging from 0 to 255. Group number 255 is privileged. For ex¬
ample, user number 0.21 has unrestricted access to all his own files but may only
access the files of other users according to the permission fields of the file. This
field is displayed by the FILES command when invoked with the +verbose option.

files +v

The default permission assigned to a file when it is created is "read". This allows
other users to read it, but they may not write to it, append to it or delete it. If de¬
sired, you may remove the read permission by using the CHATTR command as
follows.

chattr filename p=~r

QNX Manual Installation

QNX 23

The file "/config/pass" is created and updated using the editor (ED). This file
should be created by the super-user (member of group 255) and should have read
permission removed from it. It consists of a five line entry for each userid. All
lines except the USERID line should be indented by ONE tab.

USERID

** PASSWORD

tab USER NUMBER (Group.Member)

** LOGIN DIRECTORY

*4 LOGIN COMMAND

The USERID is the character string which must be entered in response to the
"Login:" prompt. It may contain any characters including blanks and control
characters.

The PASSWORD is the character string which must be entered in response to the
"Password:" prompt. If this field is left blank, then this userid does not have a
password and may be logged in without one. The password may also contain any
characters including blanks and control characters. NOTE: the leading tab is still
needed even if the password itself is absent.

The USER NUMBER is a pair of numbers between 0 and 255. The first number is
the group, the second is the member of that group. These numbers identify the user
to the system and determines his/her file access capabilities. Each userid will
typically be assigned a unique user number. However, you may assign more than
one userid the same user number if you wish them to have the same file
capabilities.

The LOGIN DIRECTORY is the name of the directory to place the user at, after
successfully logging in.

Finally, the LOGIN COMMAND is any QNX command which will be executed
upon logging in. In a student environment this should be kept consistent for all
students. Executing a user profile like "ec user.init" is a good choice.

Typical user.init

fortune

ap waiting list alarm
umail waiting
path !/cmds/!/cmdsl/H

QNX 24

Manual Installation

An exclamation mark (!) at the beginning of the LOGIN command will transfer

directly to that command. This allows custom applications to be called directly
when the user logs in without allowing them to return to a shell when the program
terminates.

The following example illustrates a simple four user file.

superman
tab dark kent

tab 25S.25S

tab /user/superman

tab IS

jasmith

tab qwerty

tab Ool

tab /user/jasmith

tab ec userinlt

jqpublic

tab

tab 0.2

tab /user/jqpublic

tab

dbase

tab abc

tab 1.0

tab /dbase/data

tab dbase

superman has been assigned group number 255 and can do anything. Userid
jqpublic has no password, and may be logged into by anyone. It also has no initial
command to execute.

In an environment where there are many users it is convenient to assign userids

based upon first and second initial followed by the last name. Mr. Jim A. Smith

would be jasmith as in the example above.

The password file must be accessible to all users when they login. In a network, it

is usually placed on the boot server node. Keep in mind that once this file exists
then you must live by its login rules. Should you corrupt it you may not be able to

log into the system. It should be pointed out that this security system is only effec¬
tive once QNX has been booted, the disk containing the password file mounted,
and the PASSON command executed (unless you booted from network). For this

reason, access to the system unit should be restricted.

QNX Manual Installation

QNX 25

By convention, QNX places user directories under the directory "/user". There will
typically be one directory for each user. The directory "/user" should be owned by
the super user and only he may create new user directories directly under it. Each
sub-directory under "/user” should be owned by the user assigned to it. The fol¬
lowing procedure for adding a new user may be followed. In the example we will
add a new user with name "jasmith" and user number 0.12.

1. Login to the super user.

2. Create the new user directory under "/user".

mkdir /user/jasmith

3. Assign the new user a number and give him ownership.

chattr /user/jasmith g=0 m=12

4. Read the file "/config/pass" into the editor and add
a password entry for the new user.

jasmith
mb xyz

tab 0.12

tab /user/jasmith
tab ec user.init

5. Write the file back and you should have successfully
added a new user to the system.

3.6 Mounting a DOS or Second QNX Partition

You can mount more than one hard disk partition at a time. When you mount the
second or third partitions you replace the name of the driver with a d-drive op¬
tion. The drive is the drive number of an already mounted partition. The partition
to mount is selected using the pa -osjype option. For example, the following will
mount two QNX partitions and one DOS partition on an AT.

mount disk 3 /drivers/disk.at pa=qnx

mount disk 4 d=3 pa=qny
mount disk 6 d=3 pa=dos

The DOS partition can only be accessed by the DOS emulator or DFS package.

QNX 26

Manual Installation

We have reserved the osjype numbers 7, 8 and 9 for QNX. When you mount a
disk .you may either specify its number or one of the following symbolic names.

pa-qex same as
pa=qey same as

pa=qnz same as
pa=dos same as

pa=7

pa=g

pa=9

pa=l or pa=4

Most of the hard disk controllers can support more than 1 physical hard disk. To
mount a second disk use the d= and p= option on the mount command. For ex¬
ample, assume that an AT controller has two 20 Meg disks attached to it, and both
have QNX partitions on them.

mount disk 3 /drivers/disk.at pa=qnx - disk 1
mount disk 4 d=3 p=2 pa=qnx - disk 2

The p= option specifies which physical_drive to use. The default is to use physical
drive 1, which is why it was not required in the initial installation.

3.8 Changing Operating System Defaults

The BOOT command allows you to specify a configuration file ([c=config_file])
which lets you change some of the operating system defaults such as the number of
open files supported.

A configjile is created and maintained by the OSCONFIG command. It is de¬
scribed in detail in the "Utilities’' manual. It takes a file name as an argument. For
example:

osconfig 3:/config/sys.cfg

would create a configuration file for a single non-networked machine. It does not
become active until you use the BOOT command to set it. For example:

boot 3:/netboot/os.2 o 10pcat c=3:/confIg/sy s.efg

You may select any file name, however, when booting over the network QNX will
automatically look for /config/sys.cfg.R« with nn replaced by your node number.
For this reason we recommend you adopt this convention, even on a single
machine, although on a single machine you may omit the ".nn" extension.

QNX Manual Installation

QNX 27

/config/sys.cfg - Single machine.

/config/sys.cfg./in - Network machine.

NOTE: When booting from hard disk you should not remove the os filename,
the driver filename or the config file name.

Inetbootlosname

/config/hdisk.cfg

/config/sys.cfg

You may copy a new file on top of them but NEVER remove them (FREE, RM,
...) and then create a new one even if they have the same name. The BOOT com¬
mand saves away the absolute start blocks of each of these files which will change

once the file is removed.

3.9 Removing the QNX loader

The bootstrap loader created by die [+qnxloader] option of the BOOT command is
compatible with that created by the DOS FDISK utility when a hard disk is par¬
titioned for the first time. However, some compatible PC’s or AT’s may have a
different bootstrap loader placed in block 1 of the disk.

If you have used the [+qnxloader] option with the BOOT command, and now find
that DOS no longer boots and you wish it to, you can use the QNX FDISK com¬
mand to remove the special signature (55AA) from the boot block. This will en¬
able the FDISK command under DOS or QNX to re-write a new loader. For exam¬
ple:

fdisk 3 +r

The ^remove option to FDISK should rarely be used and is not documented
elsewhere.

QNX 28

Manual Installation

4. Network Installation

Do not attempt network installation until you have read chapter 1

and

completed the single machine installation in chapter 2 or 3.

Now that you are successfully running QNX on one machine you can start to con¬
nect several machines in a local area network. You will need a local area network
card for each machine in the network and a version of QNX configured for the
proper number of computers (nodes ).

4.1 Hardware Installation

Please refer to the documentation which was provided with
the networking card. It should have been supplied as an
insert to be added to the standard manual.

4.2 Software Installation

Your first machine (the boot server) must boot from disk. Each other machine in
the network may optionally boot from disk or over the network, from the disk of a
boot server. It is possible to configure work stations without any disks whatso¬
ever, using only remote disk storage.

If you have three or more networking cards we recommend that you first attempt to
connect only two machines together.

In the following sections you will want to place the indicated commands in the
system initialization file of the boot server. More information on the commands
may be found in the "Utilities” manual.

onfigure

Size

When booted from floppy disk, QNX will not communicate on the network. The
netsize utility must first be executed to configure the size of your network. This

QNX Network Installation

QNX 29

utility will prompt you to insert your boot disk, and any network expansion disks

which you have purchased. A total network size will be calculated and recorded
onto the hard disk. A directory of files will also be maintained on the hard disk (in
the /netdisks directory) for informational purposes. To use netsize, you simply

type:

$ netsize

and insert boot or network expansion disks when prompted.

For details about unusual network configurations, please refer to the documenta¬
tion on NETSIZE in the utilities section of this manual.

Selecting Node Numbers

From QNX’s point of view, each card must have a unique network address. QNX
node id’s may lie between 1 and 255. You should configure your node id’s to start
at 1 and attempt to setup the node id’s to be consecutive. Most users select node 1
to be their main machine (boot server).

max machines

[Hi Setting a Remote Search Order

When a machine boots over the network it will have its search order set to the
machine it booted from. It will also inherit the date. Since all commands and files
are coming from the boot machine you must define a remote search order for the
boot server using the SEARCH command.

search 3 4-remote

You should place the remote search command in the system initialization file for
the boot server (eg. /config/sys.init.l ).

QNX 30

Netwoik Installation

If you wish non-super-users to use the hard disk you must use the NACC com¬
mand to allow network access. This command takes a list of drive numbers and
device names to allow/disallow. To allow read/write on disk 3 enter the command.

nacc 3 +read + write

Since the search order of a node which is booting over the network will be to the
boot server, you should place the network access command in the system initializa¬
tion file for the boot server. Otherwise machines will hang when they boot
because they can’t find an appropriate sys.init.iin file in their search order.

■8W®

Creating System Initialization Files

As each machine in the network boots it will attempt to execute the file
/config/sys.imt.f!H where nn is the node number of the machine. If that file does
not exist then it will try /config/sys.init (no node postfix).

config

i- 1 - 1 — 1 -r--- 1

sys. init sys.init.1■ sys. init .2 sys. init. 3
default

We recommend that sys init be a relatively harmless set of generic commands
similar to the one shipped on your boot diskette. This allows you to quickly boot a
new machine on the network. Once that machine is booting successfully you can
then create a custom sys.init.nii for it.

See the description on "Creating a System Initialization File" in chapter 3.

Create a Password File

Since any machine which has booted over the network from a boot server always
has passwords enabled, it is necessary that a password file /config/pass exists
somewhere in the search order.

QNX Network Installation

QNX31

See the description on "Creating a Password File" in chapter 3.

Starting the Netboot Task

Before a machine (boot server) can boot other machines, you must run a back¬
ground task which accepts boot requests from the network and downloads the
contents of operating system image files (< osjilejiames ) to the requesting
machines. This task is called NETBOOT and should be started by typing its name
followed by an ampersand (&) on the command line.

netboot &

You will probably wish to place this command near the end of the system
initialization file for the machine acting as the boot server.

QNX operating system boot image files (osjilejiames) are kept under the direc¬
tory /netboot. To prevent confusion, the names of the files in this directory have
been chosen to reflect the operating system they represent.

os, n.n r type

where n.n - is the version number (2.1)

r - is the release number
single digit 0.. 9

type - is a hardware machine type:

peat - IBM PC ? AT 9 PS/2 or compatible

atp - IBM AT 9 PS/2 or compatible running in protected mode

Hie following are typical boot filenames.

os.2.10pcat - PC or AT, real mode, release 0.
os.2.10atp - AT, protected mode, release 0.

4.3 Summary

Hie following chart summarizes the steps necessary to install QNX on a network.

QNX 32

Network Installation

| Configure Network Size

netsize

Install Networking Cards
Set a Remote Search Order
search 3 4-remote

Allowing Non-super-user Access
nacc 3 4read 4wrtte

Create System Initialization Files fconfig/sysdnitnn

Create a Password File If One Does not Exist
Start the Netboot Task

netboot &

A poller is a program which continually sends poll messages to all active nodes in
the network to verify their sanity. This poll message contains a list of all nodes
which the poller believes are functional. When a node receives a poll message, it
updates its list of UP nodes and replies with a positive acknowledgement. If the
poller does not receive a positive acknowledgement back after several poll cycles,
then that node is removed from the UP list. This updated list will then be sent to
all nodes during the next poll cycle.

When a node detects the transition from UP to DOWN on a poll cycle it will
automatically close all virtual circuits set up between itself and that node. This has
the effect of informing the associated QNX tasks in communication with tasks on
that node that the remote task has died. They will then reclaim resources (close
files, release memory,...) which may have been tied up by that remote task.

The poller is not necessary for the network to function. Its purpose is to provide
network wide resource reclamation in the event of a catastrophic error (machine
crash, power failure,...) at a time when that machine has allocated resources across
the network. The most common example would be the opening of files on a disk
on another node. Turning the power off on a machine which is sitting idle would
not require the poller.

QNX Netwoik Installation

QNX 33

Any node in a QNX network is capable of being a poller, however you should

only run ONE poller in the network at a time*

poll & - start poller

You may wish to place the command
alive 4-newboot

in the system initialization file of each node which boots over the network. This
will cause all nodes in the network to close all virtual circuits open to your node
then mark your node as UP. It is effectively like a crash followed by an instant
boot. The POLL command is documented in the Utilities section of this manual.

4.5 Recovery Without the Poller

If you elect not to run the poller, or if the poller node crashes you may close all
virtual circuits from your node to the crashed node using the KILLJVCS com¬
mand. This command takes a single argument which is the node which crashed.

The command

kill_vcs 3

tells the node on which the command is executed that node 3 has crashed.

You may tell your own network administrator that a node is up or down using the
ALIVE utility. Your local network administrator will refuse to attempt to set up a
virtual circuit to any node it believes is down.

alive +2 +4 -3 - set status of node

2 and 4 as UP

3 as DOWN

Both the ALIVE and POLLER command contain many options which you should
read about in the Utilities section of this manual.

During your first attempt at setting up the network, you may encounter some dif¬
ficulty. The following are some tips which can aid you in diagnosing problems:

QNX 34

Netwoik Installation

For purposes of example, we will assume the boot server is node 1. This means:

• That the operating system image files ( osJUejiames ) are in the /netboot

directory somewhere in its search order (most probably on its hard disk).

• You have a remote search order defined, given proper network access, and
have at least a 7conflg/sys.iiiit" file.

• The NETBOOT task is running in the background.

Let’s describe what should happen when you try to boot node 2:

• The "Node 2" message appears in the center of the screen on node 2.

• A flashing V appears just to the right of the "Node 2".

(while it flashes, an operating system image is being downloaded)

• The screen will clear.

• Either [l]/config/sys.inlt.2 will be executed on node 2, or if it was not
found, [l]/conflg/sys.init will run.

• The "Login:" prompt will appear.

QNX Network Installation

4.6.1 Diagnostic Tips

Although you may not want to do the following all the time, you may need to use

them as indicators during diagnostic sessions;

1) If you run the NETBOOT command (on the boot server) with the verbose

option, it will indicate on the boot server’s console when a boot request has
occurred, by which node, for which operating system image, and also if NET-
BOOT believes it was able to transmit it properly. For example:

netboot +v &

2) When you first try to get a node to boot, the contents of the /config/sys.init.fm
file should be kept very simple. Try using the sys.init shiped on the QNX boot
diskette or a one liner like:

type "Hove QNX"

3) Later, when creating more complex /config/sys.init.nn files, place the word
verbose as the first command to execute. This will echo each command to the
console as it executes. If the booting process stops somewhere during the ex¬
ecution of this file, then you will see which command is at fault.

4) If you suspect a particular card is not functioning properly, replace it with
another (if you can) and observe if the behavior remains the same or not. In
this situation you should also remove any non-essential cards from your com¬
puter in case there is a conflict which you might not be aware of. In some cases
you may even wish to test the card in another computer.

5) If you are setting up a card on an existing network, you can use the TSK and
ALIVE (if the poller is running) commands on the other nodes to see if they can
communicate with this node.

4.6.2 Symptom Checklist

The machine boots from disk instead from the network.

The card is not programmed correctly. You should select the "Boot
from Network" option.

The screen does not clear, and the "Node nn" never comes up.

QNX Network Installation

QNX 35

REASON: The networking card was not found during the power-up ROM scan

performed by die BIOS. You should try another card if you can, or
perhaps another machine. You may need need to upgrade the ROM
BIOS in your computer.

SYMPTOM : The "Node nn" comes up, but is wrong.

REASON: The card is not programmed correctly.

SYMPTOM : The "Node nn" is OK, but the Y never comes up.

REASON: Run NETBOOT in verbose mode to see if the boot server gets the

request and if it thinks it was sent properly (indicated by an
"OK").If NETBOOT cannot find the operating system image file,
"Boot file not found" is printed on the console of the booting node.

If NETBOOT does think the OS was sent properly, then the interrupt
configuration on the card may be a problem. Try programming the
card to use a different interrupt.

SYMPTOM : The "Node nn" comes up, the Y flashes, the screen clears, but the
machine hangs.

REASON: Since the screen cleared, the operating system was most probably

downloaded. If your characters are echoed back to you when you
type at the keyboard, then the system is alive, but most likely hung
either trying to find the "/config/sys.init.wii ,, file, or if it found it,
then it might have hung on a command within it.

If it hung trying to find it, then verify that the boot server has
properly defined the remote search order and given network
access for the drive on which the system initialization file resides.

If it hung during execution of the system initialization file, try put¬
ting the "verbose" command at the beginning of it to have the com¬
mands echoed as they execute.

Another possibility is the wrong operating system for the type of
machine has been downloaded.

SYMPTOM : You can’t login.

REASON: This is probably because the password file "/config/pass" cannot be

found. Either it does not exist, or if one does exist, it is not in your
current search order.

QNX36

Network Installation

This chapter will cover serial and parallel ports on your computer. There is also a
special discussion on smart serial cards. You may wish to refer to the Technical
Note called ’’Operating System Limits".

5.1 Serial

Terminals, modems and serial printers are connected to your computer using a
serial port. This serial connection is referred to as an RS-232C asynchronous link.
Some computers have 1 or 2 ports built-in while others require you to plug in an
additional adapter card. Most manuals refer to the first two serial ports as COM1
and COM2. There are a number of multi-port cards on the market which have as
many as 8 serial ports on one card. With QNX, these cards allow you to support
many users on a single machine. You can also have one or more tasks monitor
these lines for use in a process control application.

This section deals with "dumb" serial cards. Smartcards are described at
the end of this technical note.

After booting, QNX scans for serial ports at the following 10 port addresses in the
following order.

3F8 ( coml )

2F8 (com!)

280 288 290 298 2A0 2A8 2B0 2B8 3E8 2E8

Note: This is the default list and may be changed by running
the OSCONFIG program.

QNX will assign device numbers and names to each port found as follows.

1 st - $mdm

2nd - $terml

3 rd - $term2

Use the MOUNT command with no arguments to see the names and
tty numbers recognized by the system.

QNX Terminals

QNX 37

QNX does NOT poll serial lines but runs them in interrupt mode. COM1 (port
3F8) uses interrupt 4 while COM2 (port 2F8) uses interrupt 3. A multi-port card

generates a single interrupt for all (4 to 8) ports. You can usually select which
interrupt is generated. QNX has, built in support for most multi-port serial cards.

The technical support group can advise you on cards which are in use by existing
QNX customers.

Note that some multi-junction cards have two serial ports on one card.

These are usually COM1 and COM2 and each port uses its own interrupt (4 or
3). They do not share a single interrupt like a 4 or 8 port serial card.

In a PC/AT each card must be assigned a unique interrupt, they cannot be
shared. In a PS/2, interrupt sharing is allowed.

By default, QNX only enables interrupt 4. To use a serial adapter which has been
configured for interrupt 3, you must explicitly turn on interrupt 3 with the STTY

command.

stty inton=3

If you wish to use an interrupt other than 3 or 4 you must tell QNX to map that
interrupt to the serial handler by copying vector 4 into the vector selected. To
configure a card on the AT to use interrupt 5 you would execute the command:

stty intcp=4,5 inton=5

If a 4 or 8 port serial card is installed, try to configure it to respond to I/O address
280h. The 4/8 port card will only generate one interrupt for alt ports.

If you run across a card which uses I/O ports other than those scanned by QNX,
you can change QNX’s list by running the OSCONFIG command described in the
QNX manual.

5.1.2 Baud Rates and Parity

When QNX boots, it sets the baud rate and parity on all serial ports to 1200 baud, 8
bits and no parity. You will have to set the baud rate of your serial card to match
that set by the terminal, modem or serial printer. For terminals and printers we
recommend 9600 baud if possible. Modems will typically be 300, 1200 or 2400
baud. You must also set the number of data bits to 7 or 8 and the parity to one of
even, odd, mark, space or none.

QNX 38

Terminals

Data Bits Parity
7 even.

7 odd

7 mark

7 space

8 none Allows 8 bit data transmission

These parameters are changed using the STTY command. For example:

stty baud=2400 >$mdm
stty baud=9600 >$terml
stty baud=9600 par=even bits=7 >$tenn2

5.1.3 Connecting Cables (DTE vs DCE)

Most serial cards have been configured as a DTE (Data Terminal Equipment). This
means that the electrical interface thinks that it is a terminal and it can not be
directly connected to another terminal. It was meant to connect to a modem or a
printer. If you wish to connect a terminal to a DTE serial port you must make a
special cable that makes your port look like a DCE (Data Communication Equip¬
ment). Some cards have options to allow this. Most of the single port cards do
not. If the card does not have this option then you must connect what is sometimes
called a NULL modem in the serial line between your PC and he terminal.

A NULL MODEM is a cable which interchanges some of the lines. You can make
a NULL modem for a 25 pin serial connector as follows. Remember that to con¬
nect a modem or a printer you can use a straight through cable.

The signals on the following pins must be exchanged on one of the two connectors
to make a NULL MODEM:

pins 2 &3 Transmit and Receive data

pins 4 8c5 Ciear-to-send and Reqeest-to-send

pins 6 &20 Data-set-ready and Data-terminal-ready

The remaining pins should be connected directly from one connector to the other.
NOTE that in most instances, not all 25 pins need to be connected. For most
RS-232-C terminals (NOT Current Loop), only pins 2 through 8 and pin 20 need to

be connected.

QNX Terminals

QNX39

Terminal

25 PIN

Modem

1 —.....

ground

1 «...

3 <—.

tx data

2 .....

> '2

2 —>

rx data

3 <—«

5 ~

rts

4 .....

> 4

4 ———>

cts

20 ———>

dsr

6 <——

7 -—

ground

7 .....

carrier

g <_.

6 <———

dtr

20 ---

> 20

NULL MODEM

CABLE

STRAIGHT THROUGH CABLE

There are a number of serial cards on the market that have a 9 pin connector. The

pin assignments are as follows.

Signal

carrier

rx data

■3

tx data

dtr

ground

dsr

rts

cts

ring

If you must connect a serial port to a device which provides only tx data, rx data
and ground, it is a good practice to jumper the handshake lines as follows;

ground

tx data

rx data

rts

cts

dsr

carrier

dtr

QNX 40

Terminals

This jumpering will only allow software flow control to be used.

5.1.4 Setting QNX Line Editing Options

QNX can be configured to perform line editing on input and the expansion of
certain characters on output. The default settings are suitable for connecting a
terminal to QNX and having a user login.

If you wish to connect a serial printer you should disable line editing and echoing
of input characters.

stty -edit -echo >$printer_device_name

You may also wish to disable one or more character expansions using the fol¬
lowing options to STTY:

-etab Expand tabs to spaces set every 4.

-ers Expand a record separator to a carriage return linefeed.

-edei Expand a rubout to a space, backspace, space.

Many programs, such as LIST, will automatically reset and restore these expan¬
sions as needed. If you leave them enabled this has the advantage of allowing you
to directly copy text files to the printer and have them come out looking OK.

QNX separates text lines in files with a single record separator character
(hex le). If you do not have the ERS option enabled then this character will
not be expanded into a carriage return linefeed resulting in output which is
difficult to read.

When connecting a modem for outgoing calls only, you should disable both edit
and echo as with a printer. If you wish to support incoming calls, then leave the
options in their default state for a terminal. You may wish to use the COMM
program for incoming calls. It is described later on in this technical note.

5.1.5 Flow Control

QNX supports both software and hardware flow control on input or output. This
can be explained with an example.

Assume that a serial printer is connected which can print at 120 cps. A QNX
program can send data to the printer at 9600 baud which is about 960 cps. To
prevent loss of data the printer will tell QNX to stop sending just before its input
buffer is full. It can do this in one of two ways. With software flow control it will

send an XOFF (Ctrl s) character telling QNX to stop sending. When it is ready for

QNX Terminals

QNX 41

more data it will send an XON (Ctrl q) telling QNX to resume output. With hard¬
ware flow control it disables one or both of the hardware signal lines called CTS
(ciear to send) and DSR (data set ready). When it is ready for more data these
lines are re-enabled. Most terminals and printers can be set to use either hardware
or software flow control. On a terminal, software flow control is nice in that you
can type Ctrl s at the keyboard to stop QNX output and then a Ctrl q to resume.
This is the default set on the console/keyboard. With a printer there is a small
danger that you might get an XOFF but not an XON. This can be fixed by turning
the printer off and on line (the printer should send an XON when it goes online) or
by telling QNX to continue anyway using the STTY command.

stty -paged >device_name

When QNX is blocked on output because of flow control, it is referred to as
"paged".

Input flow control is the same process, but in the oposite direction. QNX will send
an XOFF/XON (software) or toggle RTS/DTR (hardware) to prevent its input
buffer from overflowing if data is received faster than a QNX application can
process it.

The defaults at power up are software flow control on output only. You can
change these using the following STTY options.

+|-hfiow - Select software or hardware flow control.

+Inflow - Enable/disable input flow control.

+|-oflow - Enable/disable output flow control.

To login on a terminal, you must ensure that the parity and baud rates are set cor¬
rectly, then type a Ctrl-z. If you do not get a login prompt, try typing a Ctrl-x
(delete any garbage in the input buffer) and a Ctrl-q (unpage incase a Ctrl-s has
paged output). If this fails, then type some letters. If they fail to echo, you may not
have properly configured your serial port(s).

5.1.7 Logging In From A Modem

You must configure your modem to auto-answer mode and simply follow the
procedure for logging in to a terminal. While this works it has two major disad¬
vantages.

L If you hang up, or the line drops, you will not be logged off.

2. You must always access the modem at the correct baud rate.

QNX 42

Terminals

With 300/1200/240(1 baud modems popular, you may not know which
baud rate to select.

To solve these problems, you may wish to run the COMM command. This
program will determine and set the baud rate and parity for the remote user. The
COMM command is described in the utilities section of your QNX manual. It
supports both dumb modems and hayes compatible modems. When carrier is lost,
COMM will kill off your program, effectively logging you off. To detect loss of
carrier it is important that the modem raise and lower the carrier detect line (pin 8)
and that your modem cable connect that line.

To place an outgoing call you will use the QTALK program. Please refer to the
QTALK documentation for details. If you require a more advanced terminal
emulator you may wish to purchase an extremely slick product called QTERM.

5.2.1 Problems

Most problems connecting serial ports can be traced to one of the following:

1. Interrupts on the serial card are not configured

properly or two cards are sharing an interrupt.

2. The I/O port on the serial card is not configured
properly or two cards are sharing an I/O port.

3. The cable is incorrect. You may need a straight through
cable or one that crosses some of the signal lines.

4. The baud rate is not correct.

stty bmd=baud_rate >%device_name

5. You have not enabled interrupts if the card uses an
interrupt other than 4. The symptom of this is a single
character being echoed.

stty mton=int__num

5.3 Parallel

Connecting a parallel printer to QNX is very easy. You do not need to worry about
interrupts, flow control or special cables as you do for serial connections. QNX
supports up to 2 parallel ports which are called

$lpt, $lpt2

QNX Terminals

QNX 43

It is rare to see more than one or two in a system.

5.4 Smartcards

A smartcard is a multi-port serial card with an onboard processor and a large
amount of memory for buffering incoming and outgoing data. There are no inter¬
face standards for smartcards, as there are for dumb cards, and you must run a
custom driver to use these cards. These cards may be more expensive than dumb
serial cards. They should be considered when:

° You have more than one channel of input data at 9600 baud.

® You have input data which cannot be flow controlled and comes
in bursts greater than 250 characters.

° You are performing nearly continuous output at 9600 baud and
must maintain that data rate on several channels.

° You need to support more than 10 serial ports. The smartcards
typically allow up to 4, 8-port cards in a system, for a total of
32 possible serial ports.

If you are only connecting terminals to QNX, then you probably do not need a
smartcard. If you are unsure, contact QNX technical support for some guide lines
as well as an up-to-date list of supported smartcards. The smartcard drivers are
available from the manufactures (the best choice) or from QUICS (the QNX up¬
date system) for download. In many cases, full source code for the driver is also
available. The driver runs as a background task. A typical invocation of a driver
would look like this:

smartcard a=d000 i=5 p=3O0 &

Start driver to talk to a card with:

dual ported memory at segment d000

interrupt 5

I/O port 300

Wait a few seconds for the card to be initialized and type the MOUNT command

with no arguments to see the new set of device names.

QNX 44

Terminals

6. Devices

QNX provides a sophisticated terminal handler for all character devices attached to
it (keyboard, display, serial communication ports). This chapter is a summary
suitable for end users.

The following information concerns itself with the default options set up for both
the console keyboard and attached terminals in a multi-tasking system. Due to
keyboard limitations of many terminals, some keys and options will apply to the
console keyboard only.

6.1.1 Alt, Shift and Ctrl

These three keys do not generate data themselves, but modify the data generated
by other keys.

The shift key is used to type upper case letters and the symbols shown on the upper
positions of the keys with dual markings.

The Ctrl key is used to generate the control codes defined in the ascii character set.

The Alt/Compose key, when used as a shift, will turn on the eighth data bit for any
key combination pressed. When typed as a data key it sets up a two character
compose sequence. Compose characters allow you to enter extended codes for
foreign language characters and special symbols. This is described later in this
section. This key is only available on the console keyboard and special QNX com¬
patible terminals.

The entire character set for the console keyboard is contained in appendix A. The
first table will apply for most terminals. The second table is specific to the console
keyboard and special QNX compatible terminals.

Users with a foreign language keyboard on their PC should refer to the KEY¬
BOARD command in the utilities section of this manual.

6.1.2 Caps Lock, Num Lock

These three keys are used to select a particular input mode.

The Caps Lock key converts all lower case letters to capital letters until you press
it again. This key is available on most terminals.

QNX Devices

QNX 45

The Num Lock key lets you type the numbers on the keypad without having to
shift. If you do use the shift key in this mode, it will allow you to access the scroll
(arrow) codes on the bottom of the keys. This key exists on PC keyboards which
share the keypad for numbers and cursor keys. Like the Caps Lock key, Num Lock
key is a toggle. Typing the key a second time will turn off Num lock mode.

If you run the CLOCK program, it will display the state of the Caps Lock, Num
Lock and Alt key in the upper right hand comer of your console display.

6.1.3 Type-Ahead

The QNX Operating System provides full type-ahead with echo and line editing.

As long as QNX is functional, your input keys will be seen and remembered. As a
general rule, whenever you enter a line, there will be a program waiting for input
which will consume it. You act as the producer and the program acts as the con¬
sumer of input lines. If there is not a program waiting on the keyboard, you may
still continue to type input lines which will be saved until a program (usually the
command interpreter(SH)) asks for them. For example, if you wanted to execute 4
programs, and each program took between 1 and 5 minutes, you could type all four
commands one afler another and go for a coffee while they finish.

The operating system has a limit of 254 characters in the type-ahead buffer. QNX
will stop echoing your characters if this limit is exceeded. This can be mistaken
for a software crash. If you keyboard does not echo, first try typing a Ctrl-x to
delete the last line in the input buffer. If you get echo but no command output try
typing a Ctrl-q to cancel output flow control. This can occur if you type or your
terminal sends a ctrl-s. If this does not help, refer to the chapters on "Connecting
Terminals To QNX" and "Tips On Using QNX".

6.1.4 Line Editing

Your keyboard/terminal can operate in one of two modes called EDIT mode and
RAW mode. In RAW mode, every character typed is immediately given to the
program asking for input. The program itself acts on each character received. The
full screen editor runs in this mode. In EDIT mode, when you enter characters on
a line, they are not passed to any program waiting for input until you type the car¬
riage return key. This allows you to correct any typing mistakes you may make.
The keyboard (terminal) input routine examines each character you type and
recognizes several keys as special. The command line interpreter (SH) runs in
EDIT mode. The following keys are special in EDIT mode. They are summarized
in appendix A.

RUB OUT (PC: back-arrow TERMINAL: Del or Rubout)

This key deletes the last character typed. The cursor will move one position to the
left, erasing the character at that position. Only characters which are typed by the
user will be erased. The cursor will not back up over a system prompt.

QNX 46

Devices

CANCEL (Ctrl-x)

This key deletes the entire line.

LEFT/RIGHT (PC: left, right arrows TERMINAL: backspace, n/a)

These two keys allow you to move your cursor back and forth over any text on
your line, changing it if desired. On a terminal these keys must be defined using
the STTY command since there is no clear standard. Most terminals support a
backspace key but some may not support a non-destructive forward space.

DELETE (PC: Del key TERMINAL: Ctrl-k)

This key deletes the character at the current cursor position. The rest of the line
will slide over to fill the gap. On a terminal this key must be defined using the
STTY command.

INSERT (PC: Ins key TERMINAL: Ctrl-n)

This key toggles insert mode. In insert mode any characters that you enter will be
inserted before the character at the cursor. Insert mode is always turned off when
you enter a CARRIAGE RETURN a BREAK or a CANCEL. On a terminal this
key must be defined usin** the STTY command.

TAB (tab key or Ctrl-i)

This key will enter a tab character in your buffer, and echo the required number of
spaces to move you to the next tab stop. In QNX, tab stops are set every four
columns with the first stop set in column five. If you try to RUBOUT a tab
character, you will only remove one displayed space on your screen even though
the TAB may have been displayed as several spaces. The TAB character in your
buffer will have been deleted. It is your display which expanded the TAB but
failed to un-expand it on the RUBOUT.

CARRIAGE-RETURN

This key causes the entered line to be made available to the user program. Carriage
returns are automatically mapped into RECORD SEPARATORS (hex le) by
default. QNX separates lines by a single record separator character in text files.
This differs from DOS which separates lines will two characters (carriage return
and linefeed) and Unix which uses a single linefeed.

PAUSE (Ctrl-s)

Suspend further system output to the terminal (until Ctrl-q).

CONTINUE (Ctrl-q)

Continue allowing any system output to be displayed.

BREAK (PC: Ctrl-Break TERMINAL: Ctrl-c or BREAK key)

This key halts execution of the currently running program which is associated with
the terminal. Any opened files will be closed, and all memory will be returned to

QNX Devices

QNX 47

the operating system. Note that some programs (such as the full screen editor) are
capable of trapping BREAK, preventing program termination via this key.

ESCAPE (Ctrl-z)

This key suspends (but does not kill) all running tasks associated with this terminal
and creates a new shell allowing you to enter commands. This key allows you to
escape from any program which has not defined its input stream to be RAW.

When you terminate the shell with a Ctrl-d you will return to the program you
suspended. Do not use Ctrl-z as a break even though the immediate effect (you get
a $ prompt) is similar. You will eventually mn out of task entries or memory since
the suspended programs remain around. Programs which do run unedited (ED)
may have been designed to look for the Ctrl-z and invoke a shell.

REBOOT (PC: Ctrl-Alt-Shift-Del - 4 keys held down)

This combination will cause QNX to reboot itself. Your open files are NOT
closed, and any which were open for write will be left busy. You can get rid of
them by using the ZAP command. This method of restart should only be used
when you have no running programs or in the rare event that QNX should "check
out" (CRASH).

DEBUG (PC: Ctrl-Alt-Esc - 3 keys held down)

This combination will suspend execution of your program and invoke the low level
assembly debugger if it has been loaded. If the debugger has not been loaded then
this key combination is ignored.

6.1.5 Compose Characters

The Alt/Compose key on your PC is a dual function key. When used as a shift it
will turn on the 8th data bit of the shifted character. For example

a - generates hex code 61
Alt a - generates hex code El

If it is depressed then released, WITHOUT typing any other key, it sets up for a
two character compose sequence. The next two characters are combined into a
single 8 bit character code. Appendix A contains a list of compose key trans¬
lations. The following brief table lists a few.

Alt (release) p i

—>

Alt (release) + -

—>

Alt (release) e 9

-->

Alt (release) 1 2

-->

Alt (release) b a

—>

pi symbol

plus or minus symbol
e accent grave symbol
hex 12 character
hex ba character

QNX 48

Devices

The last two illustrate the inputting of exact hex values.

If a program wishes to accept compose characters and differentiate them
from function and cursor keys it should enable option EFUNC. This will
precede all function and cursor keys with a hex FF. This is necessary since
the codes returned for function and cursor keys overlap the composed charac¬
ters. Programmers should refer to the documentation on the GET OPTION
library routine in the C compiler manual.

6.1.6 Input Gate

A unique feature of the QNX terminal handling software is termed the INPUT
GATE, which prevents output from being mixed with user input on the display.

If the INPUT GATE option is enabled, the operating system will stop all program
output to the display while you are entering a line of text. When the line is ended
with a carriage return, or the user deletes the entire line (via CANCEL or
RUBOUT), system output to the terminal will again be allowed. This option may
be turned off using the STTY command.

stty -igate

Programmers should note that this option is ignored when you turn off the
EDIT option. The option is meant for the console and users connecting to
terminals. It is not used for serial ports configured as raw communication
lines.

6.1.7 Recalling Command Lines

Due to QNX’s circular 256 character buffering scheme on input, it is possible to
back up or move forward in the buffer recalling previously entered lines. The
number of lines you may back up is determined by the length of each input line.
Editing a line you have backed up to may overwrite part of the following line. You
should think of the up and down arrow as a means of rolling backward and forward
through your typed lines. On a terminal you will have to define these keys using
the STTY command.

QNX Devices

QNX 49

RECALL PREVIOUS LINE (PC: up arrow TERMINAL: Ctrl-u)

This key will redisplay the previously entered line, allowing you to edit it if neces-
sary. Typing it again will recall the line previous to this and so forth. Warning:
Attempting to recall a line after a command which runs without line editing (Full
Screen Editor, Talk) may result in garbage being displayed.

RECALL NEXT LINE (PC: down arrow TERMINAL: Linefeed or CtrLj)
This key is the opposite of the up arrow and moves you forward through your type
ahead buffer. These keys must be defined using the STTY command if they are to
be used on an attached terminal.

6.2 Terminal Output

6.2.1 Attributes

Your console display supports several special attributes.

- inverse video

- underline

- blinking

- intensify

- colour

These attributes may be accessed in QNX by sending special control character
sequences to the display. These sequences apply to the console only. It is unlikely
that an attached terminal on QNX will support the same escape sequences to access
their special attributes. QNX’s escape sequences were chosen to provide a user
friendly interface, not for compatibility with any manufacturer’s line of terminal
equipment.

Users interested in writing programs which are terminal independent should
read the documentation on the TCAP utility and library.

Not all machines which QNX supports will have the same set of display at¬
tributes. QNX will map and support these attributes in a machine independent
manner. Selecting an attribute which does not exist will have no effect.

6.2.2 Output Escape Sequences

The QNX video display driver treats the Ascii ESC code (hex character lb) as a
special control code. The character following an ESC is examined, and if recog-
nked will cause some control function to be performed. An unrecognized
cha , r ?S^ followin § an ESC win be passed to the display unmodified, so to print a
real ESC character on the screen, you may send two ESC codes

QNX 50

Devices

Following is a list of the ESC sequences which are recognized by the QNX display
driver. Note that due to hardware limitations some combinations may not be pos¬
sible. In particular inverse and underline are mutually exclusive on the IBM
monochrome display. Since the QNX shell echoes each received character you can
experiment with these sequences by simply typing them in. The most commonly
typed sequence is a Ctrl-1 which will clear the screen.

QNX Devices

QNX 51

Esc (

Esc)

Esc [

Esc ]

Esc {

Esc}

Esc <

Esc >

Esc A
Esc 1
Esc C
Esc D
Esc E
Esc F
EscH •
Esc 1
Esc J
Esc K
Esc 1
Esc 2

Esc 8
EscS
Esc R
Esc @fc he

Esc I fc he

Esc - re

Esc Y re

Turn on inverse video mode. This will
also swap the foreground and background

colours set by the ESC @ sequence
Turn off inverse video mode
Turn on underline mode
Turn off underline mode
Turn on blinking mode
Turn off blinking mode
Turn on high intensity mode
Turn off high intensity mode
Move cursor UP (no wrap)

Move cursor DOWN (no wrap)

Move cursor RIGHT (no wrap)

Move cursor LEFT (no wrap)

Insert line
Delete line
Move cursor HOME
Reverse linefeed
Clear to end of screen
Clear to end of line
Switch to console 1
Switch to console 2
etc...

Switch to console 8
Save colour and attribute information
Restore colour and attribute information
Define the foreground and background colour
of displayed characters. Both/c and be
represent a single digit taken from the
colour table below.

Sets the fill colour which is used for
the bottom line when scrolling and the entire
screen when clearing via form feed.
fc is the colour of the cursor, be is
the fill colour

Position cursor at the screen coordinates

(r, c) which are given by the two characters

following the R is the row (0-24)

and c is the column (0-79). Both r and c are

offset by hexadecimal 20 (a space). Therefore,

re = <SPACExSPACE> is row zero, column zero

Same as ESC =

QNX52

Devices

As an example, the sequence

Esc@71Esc!71

will set your character and fill attribute to white on blue.

digit colour
0 black

1 blue

2 green

3 cyan

colour
red .
magenta

6 brown

7 white

COLOUR CODES #

digit
4

You should set your colour preference using ESC @ and ESC ! in your sys.init file
and follow it with an ESC S to save it away. All QNX applications which play
with the colour will print an ESC R to restore the saved colour before exiting.

QNX 'Devices

QNX 53

In addition, the following characters will cause some special action to be per¬
formed, rather than printing a character on the display...

Carriage-return.

Move cursor to column 0 of current line

Line-feed.

Move cursor down 1 position, and scroll the
screen up 1 row if necessary.

Form-feed.

Clear the display to the background attribute
defined by ESC ! sequence. Cursor returns to top left
comer (0,0).

Back-space.

Move die cursor left 1 position. Wrap around
to the previous line if necessary.

BELL

Bed.

Generate a tone for a fraction of a second.

HOME

Move cursor to top left comer of screen.

up-arrow

Move cursor up one position.

Wrap around to bottom if necessary.

down-arrow

Move cursor down one position.

Wrap around to top if necessary.

left-arrow

Move cursor left one position.

Wrap to end of previous line end if necessary.

right-arrow

Move cursor right one position.

Wrap to beginning of next line if necessary.

QNX54

Devices

7. Full Screen Consoles

Virtual consoles give you the ability to switch between several tasks, each running

on a different virtual console. For example, a developer may choose to edit
programs in one console, compile programs in another console and execute them in
yet a third console. Multiple consoles offer a definite advantage over running
programs in background in that you may examine your output and gain control at
any time. An advanced work station might run a VT1GG emulator, 3278 emulator
and another QNX application in three consoles, all concurrently, with the ability to
rapidly switch between applications.

QNX can support several virtual consoles on your PC’s physical screen. Each
virtual console is one full screen and may be thought of as a console to which you
may attach your keyboard. Your keyboard is always attached to the console which
is being displayed. The other consoles may still receive output data from tasks.

7.1 Mounting Consoles

When QNX boots, it assumes only one console. You must explicitly MOUNT
every other console you wish to use.

By default* QNX has a built-in Console Driver which will work with CGA and

EGA in text mode. Other Console/Graphics Libraries are available which support
text consoles in 43x80 mode, these are:

/drivers/glib.ega - IBM Enhanced Graphics Adapter,
/drivers/glib, vga - IBM Video Graphics Array.

If you wish to use consoles in these non-standard text modes you must mount the
proper Console/Graphics Library before you mount any of your extra consoles.

If you mount them afterwards you will be limited to a screen size of 25 by 80.

The operating system allocates system memory to store each of the consoles that
have been mounted when they are not displayed. When you mount your first
extra console, QNX will query the Console/Graphics Library which is mounted at
that time, to find out what maximum amount of space is required to store a console
(for example, the default 25x80 needs 4K, while 43x80 requires 6.8K). Once the
buffer size has been determined, it is memorized and used for all other subsequent
console mounts.

QNX Full Screen Consoles

QNX 55

QNX supports many standard devices. To determine exactly how many devices
your current version supports you should refer to the Technical Note called
"Operating System Limits". Each device has two names. A $tty nn which iden¬
tifies device nn and a symbolic name like $mdm which can also be used to
reference the device. For example, $tty3 is usually associated with $mdm. The
following illustrates how the device entries are intended to be used with physical
devices:

0 $con » keyboard

7 $term4 - serial £

1 $lpt - parallel 1

8 $term5 |

2 $Iptl - parallel 2

9 $term6 j

3 $mdm - serial 1

10 $term7 j

4 $terml

11 $iermg j

5 $tenn2

12 $tenn9 - serial 10

6 $term3 - serial 4

In practice, not all devices are used. These unused device entries may be con¬
verted into virtual consoles using the MOUNT command.

For example, the following commands will create three new consoles for a total of
four including $con. The device number of the device entry to re-use may be given
(eg. 2 for $lpt2, 5 for $temi2, etc) followed by a new name to assign to the con¬
sole. If you do not specify the device, then a free one will be selected for you. If
you specify a device, be VERY careful to specify only unused device numbers.
Typing the MOUNT command with no arguments will display the devices in your
system.

mount

The new name may be up to five characters in length.
Device not specified Device specified

mount console $conl
mount console $con2
mount console $con3

mount console 2 $conl
mount console 11 $con2
mount console 12 $con3

You will wish to place MOUNT CONSOLE commands in your system initializa¬
tion file so they will be executed automatically each time you boot.

QNX 56

Full Screen Consoles

7.2 Switching Consoles

Holding down the Ctrl key, the Alt key and then pressing the large plus key on the

keypad will step you to the next console while a Ctrl-Alt minus (keypad) will step
you to the previous console.

People may enter a particular console by holding down the Ctrl key, the Alt key

and then typing the console number (1 through 8).

Programs may switch the displayed console by writing an escape sequence to any
of the consoles:

ESC 1 - displays the first console $con
ESC 2 - displays the second console
ESC 8 - displays the eighth console
etc...

NOTE: This second scheme may seem to work if typed in by users, but data
characters are left in the device buffer, which usually confuses the application that
reads them.

At the time of this printing, certain EGA video cards on the market perform a
bit of magic allowing them to auto-switch between several graphics modes.
They also allow you to connect a monochrome or CGA monitor to the con¬
troller while in EGA compatability mode. The card does all the grayscale
interpretation required to make it work. They implement this cleverness by
generating an HO check which generates a NMI (non-maskable-interrupt)
which they vector into their ROM BIOS on the card. This trick does NOT
work in protected mode and will cause the operating system to fault, usually
the first time you attempt to switch consoles.

Fortunately, you can usually disable the INTELLIGENT capability of these
cards and make them BE a MDA, CGA, HGA or EGA controller connected
to the appropriate monitor type.

Any program may be executed in the active (displayed) console and will behave
as expected. However, some programs which write directly to the screen memory
or use the BIOS calls (int lOh) may cause problems if you switch to another con¬
sole while they are executing. The rule of thumb to use in these cases is never
switch to another console unless you are sure these programs are not going to try to
print to the screen while you are in the other console. Programs which use the
QNX I/O facilities or the high speed video interface will not have a problem. This
includes all QNX Software Systems’ utilities and products.

QNX Full Screen Consoles

QNX 57

The stty command supports a +hold option which will hold a task from

running unless it is the active console. This may be useful for a console in
graphics mode where applications always write directly to the screen memory.
Programmers can control this option from within their programs.

7.3 Initiating Commands in Other Consoles

Typing a Ctrl-z in a new console will cause the login prompt to be displayed just as
it would for any terminal.

Occasionally it may be necessary or convenient to automatically initiate a com¬
mand in the other console. This can be accomplished using the ONTTY command.

mount console 2 coni

ontty 2 login
OR

ontty 2 application

7.4 Consoles and Graphics

The default Console Driver which is part of the operating system, does not support
any graphics. However, as mentioned above, there are several Console/Graphics
Libraries which can be mounted to replace and/or augment its capabilities. These
support graphics capabilities through the compiler library interface.

These allow you to have 1 console in graphics mode at any one time, and some
allow you to switch consoles when in graphics mode, while others prevent it:

/drivers/glib.hga - Hercules Graphics Adapter.

• Text mode [ 25 by 80 monochrome ],

• Graphics mode [ 720 by 348 monochrome ].

/drivers/glib.cga - IBM Colour Graphics Adapter.

• Text mode [ 25 by 80 with 16 colours ].

® Graphics mode [ 320 by 200 with 4 colours ].

[ 640 by 200 with 2 colours ].

/drivers/glib.ega - IBM Enhanced Graphics Adapter. *

® All modes from CGA Library.

® Text mode [ 43 by 80 with 16 colours ].

QNX58

Full Screen Consoles

•Graphics mode [ 640 by 350 with 16 colours ].

/drivers/glib.vga - IBM Video Graphics Array. *

• All modes from EGA Library.

• Text mode [ 43 by 80 with 16 colours ].

• Text mode [ 50 by 80 with 16 colours ].

• Graphics mode [ 320 by 200 with 256 colours ],

• Graphics mode [ 640 by 480 with 16 colours ].

* Cannot switch consoles when In graphics mode.

For more information see the Technical Note called "Console Shared Library".

QNX Full Screen Consoles

QNX59

8. Files

8.1 File Names

Like most operating systems, QNX stores information on disks in files. You iden¬
tify a file by its name. On QNX, a filename may be from 1 to 16 characters chosen
from the set of:

- the letters of the alphabet

- the numbers 0 through 9

- the period V and the underscore 9 _ 5

- hex characters 80 through AF (foreign characters)

Upper and lower case letters are distinct. The file "Report" does not have the same
name as the file "report". Some examples of good and bad filenames follow:

John Doe Bad: contains a space

27=d Bad : contains a dash

John Doe Ok

123.7 Ok

teste Ok

Unlike some operating systems, the period is not treated as an extension se¬
parator by the QNX file system. It is just another possible character making up a
filename. To improve clarity, the user may adopt the convention of suffixing
filenames with an extension (a period followed by a few characters). The exten¬
sion is NOT enforced by the file system, only the user and perhaps the commands
that operate on files. In particular, the C compiler assumes that a C program that it
has been asked to compile ends in ".c". If asked to generate an object file it creates
a file with the ".c" replaced by a ".o".

8.2 Structure of Files

A file is regarded by QNX as a featureless, randomly addressable sequence of
bytes. No other structure of files is assumed by the operating system. Commands
which operate on files will in general impose their own structure. For example,
commands which operate on text files (p, ed, size etc...) assume that a file consists
of variable length lines, with each line terminated by an ascii RECORD SE¬
PARATOR character (hexadecimal value IE).

A file may vary in size from 1 to 1,099,511,627,771 bytes (about 1 terabyte). A file
cannot be larger than the disk which contains it.

QNX Files

QNX 61

The smallest unit of storage allocation for a file is one 512 byte disk sector. Files
need not be contiguous or preallocated to their maximum foreseeable size. QNX
will enlarge a file's size as required and if possible* allocate contiguous space for

There is a file called ’’bitmap" on each disk which contains the sector allocation of

the disk. You may display this file in hexadecimal format using the "dump" com¬
mand or pictorially using the query command.

dump 3:/bitmap
OR
query 3

query 3 +d

The total number of files a user may have on a disk is only bounded by available
disk storage.

8.3 Directories

^ J sailor! O

there is a type oi nle maintained oy me upeiaung system ^dncu a. uu ceiuty.
Directories contain the mapping between the names of files and the files them¬
selves and thus impose a structure on the file system as a whole. Each user has a
directory of files and is free to create subdirectories to contain groups of files
which are related. A directory may be read by the user, but may only be written by
privileged programs and as such, is controlled by the operating system. A direc¬
tory may contain a maximum of 32,000 files, however, if it contains subdirectories
then each subdirectory may also contain 32,000 files. This rule is then applied to
the subdirectories. For all practical purposes the number of files you create will
only be limited by the amount of disk space you have available to save their data.

The structure of the file system is hierarchical and is often called "tree structured"
since diagrams depicting it look like inverted trees with their root at the top. To
clarify this, lets consider an example where a user (gord) has three directories; one
for C programs, one for Basic programs and one for business documentation. His
file structure would look like Diagram 3.1.

QNX 62

Files

gord

basic

test

doc

gamel game2 mortgage report 1 report2

Diagram 3.1

The "leaves" (test.e gamel, etc..) ar & files and the internal nodes (gord, c, basic,

and doc) are directories. Let’s complicate our example and assume the user wants
to separate his C game programs from his C business programs. The user also
generates a series of reports each month and wants each of the monthly reports
kept separate. This may be achieved by the structure in diagram 3.2.

basic

test

doc

games

s:.ness j^n f^b ... d«ic

gamel

g anas 2

business J|
mortgage month__end

month end

Diagram 3.2

QNX Files

QNX63

Finally, let's also subdivide the directory doc into years (diagram 3.3).

doc

1986

’—I

1987

i-r~

jan feb ...

dec

I— - 1 —

feb ...

dec

month__end month__end month_end month__end month__end month end

Diagram 3.3

Note that you can use the same filename for different files under different direc¬
tories. The file system allows you to structure your files in a natural hierarchical
arrangement. To achieve this with a flat file system would be very awkward.

The previous examples have dealt with userid "gord". Since a disk may contain
many userids, "gord" is in fact just a directory under another directory called
"user". A three user disk is illustrated in Diagram 3.4.

dan

user

gord

bill

other directories

Diagram 3.4

QNX64

Files

The V’ at the top is a very special directory called the ROOT directory and each
disk has one. Your Boot diskette contains directories under the root as illustrated
in Diagram 3.5.

sys .init

inform .. .

disk .at

Diagram 3.5

Executable commands are kept under the directory "cmds" and configuration files
are kept under the directory "config". Explain files are kept under the directory
"expl". Disk drivers are under "drivers".

8.4 Pathnames

When you specify a file to QNX, you must present it in a form which uniquely
identifies it within the hierarchical directory structure. This form is called a
pathname and consists of a sequence of directory names separated by slashes,
and ending in a filename. For example the file "Is" under the directory "cmds"
could be written as the pathname

/cmds/ls

Likewise, the file "month_end" under the directory "1987" under the directory
"jan" in diagram 3.3 could be written as the pathname

/user/gord/doc/1987/jae/month_eiid

The leading slash indicates to QNX that it should begin its search at the ROOT of
the file system on your disks. In the "month_end" example, it will start its search
on the first drive in your search order and look for the directory "user". If it fails to
find it, it will then look on the next drive and so on for each drive in your search
order. Once it locates "user" at the ROOT of a disk, it will look in that directory
for the directory "gord", and if successful, it will look in directory "gord" for direc¬
tory "doc" and so on until it finally locates the file "month_end".

QNX Files

QNX 65

If you are opening a file for write, once the system has matched a directory on a
disk (ie: "user" in this case), it will not restart its search on another drive if it fails
to find a subdirectory or the file on its search down the tree. This behavior is only
important if you have two disks with a directory by the same name at the ROOT.
QNX solves this ambiguity by always stopping its search on the first disk on which
it finds a match at the ROOT. This is not true for files being opened for read,
read/write or execute. In these cases, the search will continue across all drives

fnr- Qirs ATOPt

JLOUJvlIig IU1 ail CAaCl JLJLJLclldl.

The default search order of your drives depends on how you boot.

Boot Search Path

floppy 1st floppy, 2nd floppy if present

hard disk hard disk only

network node from which you booted.

You may change this using the SEARCH command. For example if you had a
ramdisk as drive five and a hard disk as drive three you could tell QNX to search
drive five first by issuing the command:

search 5 3

Refer to the SEARCH command in the utilities section of your binder for more
information.

8.4.1 Specifying a Drive as Part of Your Pathname

You can override QNX’s sequential search of your disk drives and lock onto a
particular drive by prefixing your filename with a drive number followed by a
colon (:). As an example

backup 2:/user l:/user

would invoke the backup command with the directory "user" on drive 2 as the
source and the directory "user" on drive 1 as the destination. The command

backup 1:/ 2:1 +all

would back up all structure on the disk in drive 1 onto the disk in drive 2. Finally,
the command

dump 2:/bitmap

would only look on drive 2 for the file "bitmap" under the ROOT.

QNX 66

Files

The previous pathnames all began with a slash and cause a search to be made star¬
ting at the ROOT of the disk. If you leave off the leading slash, the search will be
made starting at your current directory. When you log in, your current directory is
set to point to the directory you logged into. For example, if you logged into "gord"
and gord had a file named ’’costs”, you could name it via its full pathname starting
from the root

/user/gord/costs

or its relative pathname starting at your current directory
costs

When QNX memorizes your current directory, it does more than just remember a
pathname. It remembers the drive and block number on the disk of your current
directory. In a QNX network the node number is also remembered. This results in
very fast access to files accessed by this method. In practice you will find that
90% of your pathnames will be relative, NOT absolute from the ROOT.

If at any time you need to specify your correct directory in a utility (such as
BACKUP), it may be indicated with a null string (""). This is also true when
opening the current directory from a program.

backup "" /dir - backup current directory to /dir

8.5.1 Changing Your Current Directory

QNX provides a command to allow you to change your current directory to point
to any directory on a disk. The command is

cd pathname

where "cd” stands for "change directory". The pathname should end in a directory
NOT a filename. For example, lets say you wanted to work on your 1987 month
end report for January. Using the structure illustrated in Diagram 3.3 you could
reference the file "month^end" by

/user/gord/doc/1987/jan/month_end

or if you had logged into userid "gord", you could access it relative to your current
directory by

QNX Files

QNX 67

doc/1987/j an/month_end

If you intend on typing this pathname more than once you should probably change

your current directory to

cd doc/1987/jan

anti leieience me me da
monthend

At any time you may return to die directory you logged into by executing the CD

command with no argument.

cd - will return to login directory

You can print your current directory using the PWD command,
owd - will print current directory on your screen

QNX allows you to move up the file structure by preceding your pathname with
up-arrows ( A ). Each up-arrow moves you up one directory level. If your current
directory was at

/user/gord/doc/1987/jan

you could reference your February monthend file as
A feb/month_end

and your 1986 jan month_end file as
A A 1986/jan/ monthend
Finally, you could "cd" yourself to "gord" with
cd AAA

which will move you up three levels.

QNX 68

Files

8.7 File Attributes and Permissions

Each QNX file has an attribute field and two permission fields associated with it.
Each field acts as a mask or a filter limiting access to a file.

The attribute field limits the access modes which may be applied to the file by any
user INCLUDING the OWNER of the file, the GROUP LEADER and the SUPER

USER.

The group permission field limits the access modes which may be applied to the
file by users which are in your group.

The other permission field limits the access modes which may be applied to die
file by other users.

Changing permissions allows you to control access to include

- yourself only

- users which are in your group

- users which are not in your group

- all users

Opening a file performs the attribute and permission checks. If any check fails,
then the open will fail with a ’’permission denied" violation. The following
diagrams illustrate the sequence of checks made.

QNX Files

QNX 69

ACCESS BY
OWNER,OF FILE

attr

I N

deny access

grant access

ACCESS BY

USER

:N SAME GROUP

attr

l N

deny access

group permissions

deny access

ACCESS BY

USER IN MOTHER GROUP

attr

I m

deny'access

other permissions

deny access

grant access

5 grant access

QNX70

Files

The attributes/permissions of a file are:

READ

WRITE

APPEND

EXECUTE

MODIFY

- You may open the file for read.

“You may open the file for write.

Previous contents are lost. If you
do not write to the file it will be
removed when you dose it. This
also gives delete capability. Files
may be opened for read/write in which
case the previous contents are not
affected by the open operation.

- You may open the file for append.

Any new information you write will
not overwrite any current information
but will be added to the end.

- You may open the file for execute.

This allows you to execute the file
as a load module or a command file
without the sh. All QNX commands
have the attribute of execute.

- You may modify the attributes/permissions
of the file.

When a new file is created it will by default have the attributes and permissions of:

attributes: READ WRITE APPEND MODIFY

permissions: READ

In addition, if the file is created by the linker and is executable, then both the at¬
tribute and permission field will also have EXECUTE capability set.

The access capabilities on a directory are quite different from those on files. Direc¬
tories are maintained by the operating system and a few specialized privileged
commands. A user should never be allowed to write to a directory, and executing a
directory is absurd. The following access capabilities exist for directories:

QNX Files

QNX 71

- You may open the directory for read.

This allows you to discover the names of
the files it contains. For example, the
’Is’ command opens the iniicatei directory
for read to list Its contents.

- You may create new files under this directory.

“ Y'011 may not pass through this directory when
matching a pathname.

- You may modify the attributes/permisslons of
the directory.

- This bit indicates that the file is a directory.

It is controlled by the operating system and a
few privileged commands.

When a new directory is created it will by default have the attributes and permis¬
sions of:

attributes: READ CREATE MODIFY DIRECTORY

permissions: MEAD DIRECTORY

The uses of these access capabilities are best explained by some examples.

1. As a user you do not want other users creating new files under your directories.
Once created they could remove write permission and you the owner of the
directory could not remove them. You can stop this by ensuring that CREATE
permission does not exist on your directories. This is the default. Shared direc¬
tories like Vtmp’ must be available for creating new files by all users and
should therefore have CREATE permission.

2. You do not want users to be able to access any of your files regardless of the
permissions on the files. Simply ensure that BLOCK permission is set on the
directory and users will be blocked from accessing all files (or sub-directories).

3. You do not want users to see the names of your files. However, you do want
one or two users or special commands to be able to access files they know the
name of. Simply remove READ and BLOCK from the directory. Adding
BLOCK would not only prevent users from seeing your files, but they could not
even access them if they guessed their names.

4. You wish all members of your group to be able to read and write a file you
own. Simple add READ and WRITE group permission to the file.

The capability of MODIFY is the most powerful since it allows you to change the

other capabilities of the file. You must have MODIFY to use the CHATTR com-

READ

CREATE

BLOCK

MODIFY

DIRECTOR!

QNX72

Files

mand on a file. Note that if you remove MODIFY from the attributes, then the file

will be fixed for all time at its current capability set. For this reason the CHATTR
command takes care never to remove MODIFY unless explicitly told to do so!

8.8 User Numbers

The owner of a file is indicated by a group number and a member number between
0 and 255 inclusive. All members of group 255 are SUPER USERS and are
privileged in the sense that they are not restricted by the permissions field of any
file, only the attributes. They can therefore read/write/execute/append/modify other
users files, regardless of the file’s permissions. Likewise, member 255 of each
group is a GROUP LEADER and may access the files of all members in that group
regardless of the permissions. All other users are constrained to access privileges
determined by both the attribute and permission fields of any files they do not
own. The owner of a file as well as its permissions are listed by the FILES com¬
mand with the +v (verbose) option.

You will be assigned the group number of the super user if there is no password
file. If a password file exists (see section ’Using QNX’) then you will be assigned
a group and member number from that file when you login.

In a multi-user system, all system directories should be owned by the super-user.
This includes the directory "/user' 1 . However, each directory under "/user” should
be owned by the user assigned to it. Since the super-user owns "/user", only he
may create new user directories under it. To change the ownership, the g= and m=
option of CHATTR should be used. For example

mkdir /user/jsmith

chattr /user/jsmith g=2 m=21

will give ownership of directory /user/jsmith to user number 2.21.

If you wish to restrict access of potentially dangerous commands, you should
remove general execute and read permission from them. For example

chattr p=-er /cmds/mount

would prevent anyone but a super-user from executing the mount command, as¬
suming that /cmds/mount is owned by user 255.255.

8.9 Device Names

Until now a pathname has referred to devices which are capable of maintaining a
directory structure, the most common being a disk drive. QNX also supports
devices which contain no internal structure and communicate a character at a time.

QNX Files

QNX 73

These are referred to as character devices and consist of

- terminals

- line printers

- modems and serial communication lines

On the Personal Computer, the keyboard and display will normally act as your
terminal. The display is not strictly a character device, but for convenience it is
treated that way by the software.

Some devices are read or write-only while other devices may be read from and
written to. Your display is an output device and your keyboard is an input device.
QNX pairs closely related devices like this and refers to them by a single name. To
identify a character device you start your pathname with a dollar ’$’. The devices
supported by QNX are

$con - Your key boar d/display (console)
$!pt - Your line printer

$lpt2 - A second line printer

SrndiTi - hirst serial port a)

$terml - Second serial port (COM 2)
$term2 - Third serial port

$null - Returns end of file on input and throws
characters away on output.

These may also be referred to as $ttyO, $ttyl ... etc. There may be more or less
devices configured depending on the version of QNX you have running on a par¬
ticular machine. The MOUNT command with no arguments will list those devices
you have configured and are installed.

mount

QNX goes to some length to treat character devices and files as similarly as pos¬
sible. This is called device independent I/O. What this means is that any com¬
mand which expects to read or write to a device may also read or write to a file
without modification. The reverse is also true. As an example the CP {copy)
command is typically used to copy files.

cp source Jile destination Jile
Either or both pathnames may be a character device.

QNX 74

Files

cp sourcejile $lpt .

Anyplace where a pathname is acceptable, you may usually enter a device name. A
device name is considered a subset of the class of pathnames.

The QNX network links all machines together. Each node (machine) contains a
file system which handles all file requests to disks attached to it. These requests
may come from local tasks or remote tasks running on other nodes. The network
extends the syntax for a pathname to include the node number on which the file or
device exists. The node number is enclosed in square brackets and precedes the
pathname. For example, the P command

p 3 :/user/dtdodge/data

would look on disk drive 3 on my node while
p [4]3:/iiser/dtdodge/data

would look on disk drive 3 of node 4. This represents a totally specified path¬
name. It should be noted that there are no artificial restrictions placed on the in-
dicated drive. Drive 3 may be a floppy, hard disk or ramdisk. If a driver exists, it
may be an optical disk or x.25 linking servicing the entire network.

A missing node number will always default to your local node.

g.10.1 Remote Search Order

If the drive is omitted then
p /user/dtdodge/data

would use the search order on my node to search for the file on my drives. When a
node is specified

p [4]/user/dfdodge/data

then the search order on node 4 is used and a search is made across it’s drives.

Each node maintains two search orders, one for local requests and one for remote
requests.

search S 3 - search drive 5 then drive 3

search 3 +remote - search drive 3 for remote access

QNX Files

QNX 75

Ill the above example, assume drive 3 is a hard disk and drive 5 is a ramdisk. The
local users will search their ramdisk then their hard disk. A user on another node
will only search the hard disk.

8*10*2 Automatic Remote Searching

You may specify a node in place of a drive to the SEARCH command. The com¬
mand

search 5 [4]

would search drive 5 (probably a ramdisk) then search on node 4 using its remote
search order. This would be a typical search order for a node without it’s own hard
disk. Node 4 would probably contain a hard disk and be thought of as a file ser¬
ver. It is possible for node 4 to also specify a node in its search command.

search 3 [5] +reinote

This would cause another indirection to node 5 and a search through its drives

using its remote search order. If node 5 contains a node in it’s search order it is
skipped. Only two levels of indirection are allowed. The second level allows a
means of redirecting all file system requests to another node in one operation.
Assume that node 1 was a file server and node 32 is a backup file server. The
normal remote search order for node 1 might be

search 3 +remote

All requests could be referred to node 32 with the command
search [32] +remote

The following diagram illustrates a complex search across several nodes.

NODE 1

search 3

[2] [3] 1

- local search

NODE 2

search 2

3 +remote

- remote search

NODE 3

search 2

[4] +remote

- remote search

NODE 4

search 2

+remote

- remote search

QNX 76

Files

An access to /path on node 1 would attempt to open the following files:

3:/path

[2]2:/path

[2] 3:/path

[3] 2:/path

[4] 2:/path
l:/path

8.10.3 Remote Current Directory

Your current directory may be on any drive on any node in the network. Simply
precede the CD command with a node number

cd [4]/user/dtdodge

The PWD command will print out the pathname of your complete current direc¬
tory, indicating both the node and drive.

pwd

8.10.4 Mounting A Remote Disk

There are a small subset of QNX commands and library routines which take a
drive number as an argument. Their syntax does not allow for the specification of'
a node number. To overcome this restriction the MOUNT command allows you to
mount a virtual disk. The command

mount remdisk 7 n=4 d=3

will map all requests to disk 7 into node 4 disk 3. You may remap a virtual drive
at any time.

mount remdisk 7 n=4 d=3
dcheck 7

mount remdisk 7 n=6 d=l
dcheck 7

The concept of virtual disks is in fact the only means of remote access offered by
most other networking systems. You might wish to consider it as an alternative to
node numbers in your search command. The following will give you your own
ramdisk and equivalence virtual drive 3 to the hardisk on node 1.

QNX Files

QNX 77

mount remdisk 3 n=l d=3
mount ramdisk 5 s=64k
search 5 3

- remote hardisk

- local ramdisk

8.10.5 Network Devices

A device name may be prefixed by a node number in the same manner as a path¬
name.

cp file $lpt - local line printer

cp file [4]$lpt - line printer on node 4

8.10.6 Limiting Network Access

Now that we have given you the syntax and mechanism for completely generalized
access to any device in the system, it becomes necessary to restrict access. You
may not wish to share your local ramdisk and floppy with another work station.
Likewise, you may consider a dot matrix line printer connected to your computer
as your exclusive property. The NACC command can be used to control every
device attached to your machine. The default is NOT to grant access. You may
enable READ and or WRITE permission as desired. For example

nacc 2 $mdm +read +write - read and write for drive 2

and $mdm

nacc 3 +read - read access only for drive 3

nacc CPU + write - allow remote task creates

The last example allows other nodes to create and execute programs on your node.
This very advanced feature separates QNX as a true fifth generation operating
system. Please refer to the documentation on the NACC command for further
information.

QNX 78

Files

9. The Command Interpreter (Shell)

The command interpreter, referred to as the "shell", acts as the interface between
the user and QNX. To the shell, a command is a sequence of words separated by
spaces.

command argl arg2... argn

The first word is treated as the name of an executable file (the command name) and
all other words are considered as arguments to the command. Upper and lower
case letters are different. If the command name begins with a slash then a search is
made for the pathname exactly as specified, otherwise, the string "/cmds/" is
prefixed to the pathname first. If after prefixing with "/cmds/" the pathname can
not be found then the prefix is removed and a search is made under your current
directory. For example, the command

p data

would cause a search for the executable file
/cmds/p

and only if that failed would it look for

under your current directory.

This default search path may be changed by the PATH command which is
described later in this chapter.

The arguments are collected by the shell and passed to the command as strings.

9.1 Shell Prompt

The shell will prompt for input with a character followed by a space. The
character prompt is different for the three classes of QNX users.

$ - Super User
# - Group Leader
% - Regular User

QNX Shell

QNX 79

The PROMPTT shell command may be used to precede the prompt with your tty
number. This is useful on the console with multiple consoles.

9.2 Command Input/Output Redirection

When a command begins execution, it opens three files referred to as its standard
input, standard output and standard error output. By default these all refer to your
terminal. The shell is able to change these default assignments by recognizing the
constructs:

>pathname
>*pathname
»pathname
»*pathname
<pathname

- redirect standard output to pathname

- redirect error output to pathname

- redirect and append standard output to pathname

- redirect and append error output to pathname

- redirect input from pathname

As an example, the command "Is" ordinarily lists on your terminal the names of the
files in your current directory. The command

Is >my_files

would redirect the output to the file "my_files". Likewise

Is >$lpt

would print them on the line printer. An interesting example of redirecting your
standard input allows you to invoke the line editor with a script of editor com¬
mands.

led file <scriptJile

Although the redirection character and following pathname appear to be an argu¬
ment to the command, they are in fact interpreted completely by the shell and not
passed to the command at all. Thus no special coding is required within the com¬
mand to handle input/output redirection. The redirection applies only to the com¬
mand executed and not subsequently executed commands.

Programs which are started in the /config/sys.init.ftff files have their standard input
set to $null. This means that programs which read data from standard input will
get EOF. If you wish to start a task which can read from standard input you must
redirect it. For example:

rayprog < $ttyO

QNX80

Shell

You can also use the ONTTY command:

ontty $ttyO myprog
ontty $tty5 my__ottier jprog

C programmers may note that redirected HO pathnames are passed to their

program as argvjargc] thru argv[argc + 2]. The current path is in argvfargc
+ JJ. A value of zero indicates no redirection .

9.3 Quoting

Sinee arguments are separated by spaces it is not directly possible to pass spaces as

arguments or a single argument containing a space to a command. To overcome

this limitation the shell allows you to enclose in double quotes any argument which
you want passed to a command as is. Some examples of quoting follow:

cmd " "
cmd " 15

cmd ,f >file ,f

cmd "abc def* ghi

■ invoke command with one argument
consisting of a space

* invoke command with one argument
consisting of a null string

■ invoke command with one argument
consisting of the string ">file"

* invoke command with two arguments
consisting of "abc def 1 and "ghi".

In the third example the ’>’ is protected from the shell and cmd will not have its
output redirected. In the fourth example the string "abc def with an embedded
space is passed as one argument, not two. In all cases the double quotes are
stopped off the argument before passing it to the command.

There are cases where you may only wish to protect one character (perhaps a
leading > or ’<’ on an argument) or the quote character itself. The shell under-
stands the backslash character as a character which protects the character following
it from the shell. The backslash character is NOT passed as part of the argument
You may pass a backslash to a command by entering two of them side by side
i he first simply protects the second. Therefore the cmd line

cmd \"hello" \\ \>fil e

QNX Shell

QNX81

would pass three arguments to cmd.

"hello”

>file

A backslash does not lose it special significance when in double quotes.

9.4 Filename Generation

The shell treats the characters star (*) and question mark (?) special in the context
of a filename. They are often referred to as global filename characters. A ? in a
filename indicates that any character may occupy that position. A * in a filename
indicates that zero or more characters may occupy that position. A search is made
of all filenames in the current directory. Any files which match will replace the
filename which contains the * and or ?. It is often convenient to think of the * and
? forming a pattern which may match zero or more filenames. Since the pattern
may be expanded into many filenames there is the possibility that you may over¬
flow the 512 byte maximum command line. If this happens you will get the mes¬
sage LINE TOO LONG. The following examples will illustrate a few simple
expansions.

type *
type *.c
type a*
type *a*
type *.?
type p=*

list all files in current directory

list files which end in \c’

list files which start with an ’a’

list files which contain an ’a’

list files with a one character dot extension

type the string ? p=*’

The last example illustrates that a filename will only be expanded if the characters
around it are valid filename characters. The equals (=) is an invalid filename
character, so no expansion was attempted. This check allows commands like WS,
FILES etc to accept an argument of the form

p -pattern

without having to worry about the shell interpreting and expanding the pattern
itself. Note that the shell can not handle an embedded * in a pathname.

type /dir/* - not supported

You should use extreme caution when using *. The innocent looking command

QNX82

Shell

frel *

will release ALL files at your current directory level!

9.5 Querying

When a command is followed by a question mark ’?’, it indicates that the com¬
mand should explain itself.

In C programs, the command is informed by setting the number of arguments
passed to it to zero. Each command normally receives at least one argument
which is the command name itself

All commands supplied by QNX have adopted this convention. The command

Is ?

will inform the LS command to print a terse usage message. This will often save
you from pulling out your utilities manual when you are unsure of a command’s
syntax. The ? should be the last character on a line.

9.6 Background Tasks

In QNX, the ampersand character is used to run commands in background
(deferred). The task will be detached from your console and both the new com¬
mand and your command shell will run concurrently. The task-id of the new task
will be displayed on your console (this can be disabled) followed by the $,# or %
prompt from the shell indicating that you may continue to execute more com¬
mands. If you do not redirect the standard input for the new command it will be
changed to the device $null, NOT your keyboard. The new task created will be
immune from keyboard breaks. If you wish to explicitly kill it before it terminates,
you may use the BREAK, KILL or SLAY command. For example

slay dragon

will kill the task with task name "dragon". If you are not the SUPER USER you
may only kill tasks which you yourself have created.

The priority of the new task may be decreased by following the with a minus

sign. This is often used for programs you do not want to interfere with your
keyboard response. This is especially true when you are in the full screen editor.

. cc cprog &-

QNX Shell

QNX 83

The LIST command is an excellent example of a command which can be run
background to increase your productivity. Issuing more than one LIST command
(from one or more terminals) will result in the requests being queued up waiting
for the printer. The following would queue up 3 list requests.

list cprog.c &
list x=myfi!es &
list *.c &

In a network system or even a large single machine multi-user system you
should consider using the spooler instead of direct calls to list.

9.7 Multiple Commands On a Line

You can place several commands on a line by separating them with a semicolon
(;). For example.

Is ; task

If you wish to pass a real semicolon to a program you must quote it with double
quotes or a backslash.

The or-bar (I) character is used to set up pipes between commands. This connects
the standard output of one command into the standard input of the next command.
The effect of the command

files | sort f=l

is the same as

files >file
sort <file f=l

The commands are connected by a pipe, implemented in QNX as a temporary file.
The file used will be placed under the directory 7tmp\ When the shell dies it will
remove any pipe files it may have created. You may change the names of the
temporary files used with the ’defpipe’ command. For example, the command:

QNX 84

Shell

defpipe #$

will use a temporary file under the current directory with the name of the task

number of the shell. A simpler example

defpipe myjpipe
will use temporary files

mypipel and myjpipe2

at the current directory level. Placing the temporary files on RAMDISK has the
advantage of speed.

Commands which are designed to read their standard input, transform the data in
some way, then write to their standard output are often referred to as filters. You
may connect several of these commands together via pipes in which each com¬
mand performs one operation on the data stream.

9.9 Comment Lines

Any input line to the shell which begins with a control character or a double quote
will be ignored. These lines may be used for comments.

9.10 Executing Commands on Another Node

If a line is preceded with a node number in square brackets, the shell will attempt
to run the following command on the indicated node. The default standard input,

output and error will all be directed back to your terminal. The closing square
bracket must be followed by a space to prevent confusion with a pathname.

[4] task

[4]task

. [2] [4] task

[2] cc [§]/dii7prog

[1] list data
[1] ontty 3 comm

[1] ontty 3 dbadmin &

Run the task command on node.4
Load the task command from node
4 and run it on this node
Load the task command from node
4 and run in on node 2
Compile on node 2 the program
Vdir/prog.c’ found on node 5.

Rue the list command on node 1.

Run comm on node 1 and have it
attach to $tty3 on that node.

Run dbadmin on node 1 in background.
All messages will go to $tty3 on that
node. No vc’s back to originating node.

QNX Shell

QNX85

[1] login

- Create LOGIN on node 1.

The last example would allow you to effectively login to node 1 as a virtual con¬
sole. All subsequently executed commands would now be run on node 1. Typing
a Ctrl-d would log you off and return you back to the shell on your current node.
You may only create tasks on other nodes if

- You are the Network Super User (255.255) 0
OR - That node has CPU write set using the NACC command.

OR « The command is owned by the Super User and has
been patched to have overriding remote create.

Make sure you have NACC permission to write to your own console
from the remote node!

9.11 Command Files

The command interpreter normally takes its input from the terminal. In the case of
a command file it will take its input from a file containing QNX commands..

During the processing of a command file a question mark (?) at the start of a com¬
mand line will stop execution of the command file if that command returns a non¬
zero status. A command file can call other command files.

9.11.1 Built-In Shell Variables

The shell has a number of built in variables which may be referenced as #c where c
is a single character. The #c sequence is replaced by a character string. If there is
no #c replacement then then #c is replaced with the null string. All built-in shell
variables with the exception of #u are expanded as numbers in the current base. If
the base is 16 they are expanded as 4 hexadecimal digits and if the base is 10 they
are expanded as a 5 digit unsigned number. The default base is 16. For example:

Base 16 Base 10

0000 00000

000c 00012

8000 32768

You may turn the leading zeros on or off using
the ” zeros on/off f command.

The built in variables are:

## - number of arguments

#% - task number of shell

QNX 86

Shell

#1 to

- task id of shell

- exit status of last command

- task id of last background task

- cyclic number which changes each second

- group number of user

- accept a line from the keyboard

- member number of user

- node number

- tty number

- userid of user

- qnx version number

- name of shell command

- arguments passed to shell command

- all arguments #1... #nn

9.11.2 User Shell Variables

The shell supports 10 integer and 10 string variables which may be read and
modified by the user. Integer variables by default expand as numbers in the cur¬
rent base (same manner as built in variables) and string variables expand as text
strings. You can force an integer variable to expand in any base by placing a Y or
V in the name as follows.

#i0 - expand iO using current base

#it0 - expand iO using base 10

#ix0 - expand iO using base 16

You can perform arithmetic on the integer variables. They are modified using the
SET VAR shell command and expanded using the following # notation:

#i0 to #i9 - integer user variable

#s0 to #s9 - string user variable

For example, the following line would read a line of text from the terminal and
save it in a string variable.

setvar = sO #k

Assignment and arithmetic is also straight forward.

setvar = iO 123

setvar = iO 0tl23

setvar = iO 0x123
setvar + il #i0

set iO to 123 using current base
set iO to 123 using base 10
set iO to 123 using base 16
add iO to il updating il

QNX Shell

QNX 87

Please refer to the SET VAR command in the UTILITIES section of the manual

under the SH utility.

9.10 Executing Shell Commands

Command files may be executed explicitly using the SH command
sh cmdfile argl arg2... arg9

or implicity by placing execute permission on the file and typing its name as a
command.

efiattr a=+e p=+e cmd_file - need only do this once

cmd_file argl arg2... arg9

The arguments argl, ...arg9 may be referenced as #1, ...#9 in the command file.
For example a command file called rename, containing the line

chattr n=#2 ffi

would be invoked by either

rename newname oldname
OR

sli /cmds/rename newname oldname
The first example requires that the file have execute permission,
chattr /cmds/rename a=+e p=+e

QNX88

Shell

9.12 Local Shell Commands

The shell examines each command entered and interprets a few special ones itself,
rather than passing them off to the operating system to execute. These commands
either modify the shell’s interface or are inconvenient to implement as regular
system commands. Each command is described in the "Utilities" section of this
manual. The following list summarizes each command’s function.

back

- suppress background tid

base base

- base for number expansions

break taskjd

- break a task

cd [directory]

-change directory

debug [text]

-debug a command

defpipe path

- pipe temp files

ec shettjile

-execute sh file

else

»conditional

eudif

-end a block if

exit [status]

- exit shell with status

goto label

-transfer control

if test cmd

- conditional

kill taskjd ...

- kill a task

ontty tty cmd

- create task on another tty

passon

- password protection

path searckpath

- change command search path

pause

- pause for carriage return

pri [+\~]number

»set priority

prompt!

- display tty number

setvar op var val

- set variable

sharoff

- don’t share code segments

sharon

- share code segments

shift

- shift # args down one

stype [text]*

»type arguments

sysup

- set system up flag

then

»conditional

trap [label]

- trap keyboard breaks

type [text]*

- type arguments

verbose

- toggle verbose mode

zeros on/off

- toggle verbose mode

QNX Shell

QNX89

9.13 Quick Reference to the Shell

The syntax of a shell command line is

[?] [!] [node] command argl arg2...

The ? option will abort the shell on a bad exit status. The ! option will transform
into the command instead of creating an extra shell for its execution. If you do this
in a shell file, no commands beyond the one transformed into will be executed.

QNX90

Shell

SHELL VARIABLES

All number expansions are 4 digit

leading zero hexadecimal by default

## - number of arguments

#? - last exit status

#$ - shell task id

#% - shell task number

#& - last background task id

#0-9 - argument 0 to 9

#c - cyclic number

#g - group number

#k - take 1 line from keyboard

#m - member number

#n - node number

#t - tty number

#u - user name

#v - qnx version number

#* - ALL arguments

#i0-9 - integer variable

#s0-9 - string variable

LABEL

\name

IO REDIRECTION
< - standard input

> - standard output

» - standard output (append)

>* - standard error

»* - standard error (append)

I - pipe (uses tmp files)

; - cmd separator

Leading TABS and SPACES are
ignored and may be used for
indentation

USER COMMANDS

base

break

task id

path

debug

[command]

defpipe path

command_file

else

endif

exit

[hex number]

goto

label

if+f

filename [cmd

then]

if+d

dirname [cmd

then]

if+m

filename [cmd

then]

if +a

nodeid [cmd

then]

if eq

str pat [cmd

then]

if ne

str pat [cmd

then]

if It

str str [cmd

then]

if ge

str str [cmd

then]

kin

task id

ontty

ttynum command

passon

path

Ipathlpathl....

pause

pri

[+\-]number

promptt

setvar

= var value

setvar

1 var value

setvar

+ var value

setvar

- var value

setvar

x var value

setvar

/ var value

setvar

% var value

shift

stype

[text]*

sysup

type

[text]*

trap

[label]

verbose

QNX Shell

QNX 91

QNX92

Shell

10. Tasks

This section is an overview of the concept of multi-tasking in the QNX operating
'system. The discussion starts off very simply and progresses to the more complex
issues and mechanisms within the operating system.

10.1 Introduction

It is by no means necessary to understand the underlying principles on which QNX
is based in order to use QNX. For most users in a multi-user system, QNX will
simply be an environment in which to run an application program on the same
personal computer at the same time as someone else. How this is accomplished
need not be known. However, a basic understanding is a definite asset.

hi its simplest form, a task may be thought of as a program which accomplishes a
particular task. In a multi-tasking operating system it is possible for several dif¬
ferent tasks (programs) to be executing (running) at the same time. The operating
system accomplishes this by sharing the computer among the various tasks compe¬
ting for it. In a single tasking system the computer spends most of its time waiting
on the user. At the speed at which most users enter characters, the computer could
easily have read a thousand times that many characters. It is this speed that allows
a multi-tasking system to appear to mn more than one program at once. In fact the
system takes turns running the various programs. The rules governing which task
to run and when are complex but can be summarized as follows.

1. No task which is blocked (typically for input or output) will run. This means
that a user program waiting for input will NOT compete with other tasks which
are ready to run.

2. No task is allowed to mn continuously for more than a fraction of a second (set
by SLICE utility) if there is another task waiting. This prevents one task which
is performing long complex calculations from locking all others out. Unlike
point 1 above, the other tasks will be affected since they may now have to wait
a fraction of a second for their turn to execute. In a multi-user system this is
seen as a slight delay in response to commands. Should an appreciable number
of tasks all consume their maximum time limit then response may suffer
noticeably. In QNX, if eight users run a program which takes several seconds
of dedicated processor time, then each program will appear to take eight times
as long. Typically this does not occur because most tasks frequently request
input/output.

3. Tasks may be assigned priorities such that higher priority tasks will never relin¬
quish the processor to lower priority tasks. The time sharing of point 2 only
applies to tasks at the same priority.

QNX Tasks

QNX 93

10.2 System Tasks

When QNX is booted, five system tasks are created. These tasks run at a priority
which is higher than any user created tasks. Each system task performs a well
defined function as follows.

TASK ADMINISTRATOR

This task is responsible for creating and destroying tasks. It is also respons¬
ible for allocating memory for the tasks. This task runs at priority one, which is
the highest task priority in the system.

FILE SYSTEM ADMINISTRATOR

This task is responsible for the file system. It handles all requests to open,
close, read and write to files. This task runs at priority three.

DEVICE ADMINISTRATOR

This task is responsible for all character devices attached to the system. This
includes your terminal, the line printer, etc. It handles all requests to open, close,
read and write to devices. This task runs at priority two.

IDLE ADMINISTRATOR

This task simply consumes any spare processor time. Since this task runs at
the lowest possible priority in the system (15), it only runs when QNX has nothing
else to do. It therefore does not affect system performance.

NETWORK ADMINISTRATOR

This task is responsible for communication over the local area network. It
handles all data requests which must be transmitted over the network. This task
runs at priority 3. If you do not have a networking card installed, this task is not
needed and will terminate itself.

There are a other tasks which may be created after the system is running. Al¬
though not essential for the system to run, they provide valuable services. They
are described below.

TIMER ADMINISTRATOR

This task is responsible for running a wakeup service. Any task can request
to go to sleep for a specified period of time and this task will wake it up when that
period elapses. It is also capable of signaling ports, setting exceptions and forcing
a task ready. C programmers are referred to the file "/lib/timer.h M and the library
routine settimerQ. The timer administrator may be started by typing (or placing
in your "/config/sys.init" file) the command.

timer &

QNX 94

Tasks

SPOOLDEV ADMINISTRATOR

This task creates virtual devices which spool information away to disk. This
allows several people to use the device at the same time. When they close the
device, the file is submitted to a real device in a first come first served order.

LOCKER ADMINISTRATOR

This task supports record locking and concurrent file sharing. The record
locking is compatible with that found in Unix System V.

QUEUE ADMINISTRATOR

This task supports named queues which supplement QNX’s normal methods
of intertask messaging.

User tasks request services from these system tasks by sending messages to them.
Upon sending a message the user task blocks waiting for the system task to receive
the message, process it, then reply with some result. System tasks NEVER send to
user tasks. The life of a system task can be summarized as follows.

- Block awaiting a message.

- When a message arrives, process the request and
if the request can be satisfied reply indicating
the result.

- If the request can not be satisfied immediately, then
remember it and wait for another message.

When the request can be satisfied, often as the
result of another received message, reply to the
waiting task at that point.

When running in a network, these messages may originate from other nodes on the
network. The receiving task need not differentiate between local and remote mes¬
sages.

10.3 Inter-task Communication

QNX supports three types of inter-task communication.

1. Messages

send (tid, snd_msg, rep_msg, size)
receive (tid, rcvjmsg, size)
reply (tid, repjmsg, size)
read_msg (tid, rcvjnsg, size)
write_msg (tid, rep_msg, size)
vc_create (nid, tid, size)

2. Ports

QNX Tasks

QNX 95

attach (port)
detach (port)
signal (port)
csignal (port)

3, Exceptions

set_exception (tid, sysexc, usr_exc)

10.3.1 Messages

A message consists of a sequence of data bytes from 0 to 65,535 bytes in length.
Messages between nodes on a network are limited to the size of the virtual circuit
buffer which was created for this communication.

The contents of a message will usually fit a predefined structure agreed upon by
both the sender of a message and the receiver. A receiving task may receive more
than one type of message, with each message having a different structure. In this
case the first byte of the message will usually indicate its type. Based upon this
message type the receiver may then apply the proper structure for extracting the
various fields within the message. The operating system does NOT check for
consistency in message types between tasks. It considers a message to be a se¬
quence of data bytes and does not examine or assume any structure on the message
itself. This view is consistent with that taken by the file system concerning the
contents of files. The convention of using the first byte of the message to indicate
message type may (or may not) be adopted by the communicating tasks themsel¬
ves.

When a task SENDS a message to another task it will block until the receiving task
RECEIVES the message and then REPLIES. When a task does a RECEIVE
waiting for a message it will block until one is SENT to it. The operation of
REPLY does not block. This presents two scenarios depending upon whether the
send occurs before or after the receive.

QNX96

Tasks

TASK A
A sends to B

TASKS

- A Mocked

B RECEIVES from A
. - B processes the message
B REPLYS to A

- A continues

Diagram 10.1

TASK A.

A sends to B
. - A blocked

! B

. - A continues

TASKS

B RECEIVES from A

e - B Mocked

. - B continues

. - B processes the message

REPLYS to A

Diagram 10.2

A physical transfer occurs at the point of the receive in Diagram 10.1 and at the
point of the send in Diagram 10.2. This can be thought of as the synchronized
connection point between the two tasks. Messages implement a totally syn¬
chronized communication.

During the REPLY operation the receiver may also reply with 0 to 65,535 bytes of
information back to the sender. The transfer occurs immediately and does not
block since the sender is already blocked awaiting a reply.

There are two types of receives, general and specific. A general receive may be
satisfied by any sending task while a specific receive will only be satisfied by the
one task indicated in the receive. All operating systems tasks perform general

QNX Tasks

QNX97

receives since they do not. know beforehand the identity of .the user tasks sending
to them; Sending to a task which does not exist or dies before replying will un¬
block the sending task. Likewise, performing a specific receive on a task which
does not exist or dies before sending will unblock the receiver.

Should more than one task send to the same receiving task, they will each block
and. queue up on the receiving task. As the task performs RECEIVE operations it ,
will receive the messages in die time order that they were sent except in the case of
a specific receive. In this case it will receive from that task only, regardless of de¬
position in die queue.

Should two tasks send to each other at the same time, they will both block on each
other resulting in a deadlock situation. This can be easily avoided by careful de¬
sign and by following these guide lines.

L If possible, design your programs such that
one task is a producer (sender) and the other
a consumer (receiver).

jU o jli iWU wtSiiCo IviLtJJL isvIlCt ILO cdlMtl Mllifcii., liikdJi&tl Mil

a very rigid protocol stating when each may send
and the other receive. A much better solution
would be to create a third task which only performs
receives, and have the other tasks send to it.

The middle task would then reply appropriately
to each task. This middle task is often referred
to as an agent The QUEUE manager is an example of
a generalized agent task.

The queueing of sending tasks provides a mechanism for controlled, sequential
access to a resource. Complex issues of synchronization, critical sections and
semaphores are handled in a clear and uniform manner. For example, the classic
problem of providing secure, controlled access to a database from multiple tasks
(users) may be greatly simplified by placing a task between the files making up the
database and the requesting tasks. The database administrator would now receive
synchronized sequential requests to act upon the database. It would provide the
intelligent interface to the file system. The file system need not contain complex
record locking facilities. These are provided by the administrator task in a manner
which is in harmony with the stmcture of the data. The task can also resolve ques¬
tions of access permissions, access statistics, access billing etc., a job which should
not be performed by the file system or operating system.

The following example is perhaps the most common occurrence in the QNX
operating system.

QNX 98

Tasks

1. User task A sends a message to the device administrator requesting a line of
input. At this point task A is SEND blocked and will not compete for the

processor.

2. The device administrator receives the message from task A and starts to ran.
Just before it received the message it would probably have been RECEIVE

blocked awaiting a message.

3. Task A goes from the SEND blocked state to a REPLY blocked state. It’s mes¬
sage has been received but it is still blocked awaiting a reply.

4. The device administrator checks to see if there is a line waiting from the ter¬
minal indicated in the message. Lets assume that there is not. The device ad¬
ministrator will then remember task A’s request and again RECEIVE block
waiting for another message.

5. Sometime later, a user types carriage return on the terminal Task A has reque¬
sted a line from. The driver associated with that device sends a signal to the
device administrator saying a line is available.

6. The device administrator unblocks, and replies to task A with a message con¬
taining the line. It then RECEIVE blocks waiting for another message.

7. Task A unblocks and starts running with a message containing the line.

10.3.1a Death of a Task

When a task dies (for any reason) it sends a message to each QNX administrator
informing it of it’s death. This allows the administrator to clean up any resources
allocated by the task before its death. Users who write their own system tasks may
request that they also receive this message when tasks die.

10.3.1b Messages Across the Network

The QNX network extends the range of the message primitives across a local area
network. It is this capability which truly separates QNX from other operating
systems which claim local area network support. QNX integrates the local area

network right into the heart of the operating system, at the fundamental level of

inter-task communication.

In the above example, TASK A sent a message to the device administrator to get a

line of input from a device. There is no need for the two tasks to be on the same
node. This means that a task on one node may communicate directly with any
device on any node in the system. It just has to send to the appropriate device
administrator task. This also applies to the file system administrator and the task
administrator.

To open a file, a user task sends an open message followed by read and write mes¬
sages to the file system task. The user task may therefore access any floppy, hard
or ramdisk on any node by sending messages to the file system task on any node.

QNX Tasks

QNX 99

To create a new task, a user task sends a create message to the task administrator.
By sending this message to the task administrator on another node you may ex¬
ecute remote task creations across the network.

10.3.1c Virtual Circuits

In these examples, the receiving task did not have to perform any special action to
receive or reply to messages from remote tasks. It is the responsibility of the sen¬
ding task to set up the communication path to the receiver. This is accomplished
by a QNX primitive which establishes a VIRTUAL CIRCUIT between the sending
and receiving task. This primitive

vid = vc_create(node_id, task_id, messagesize)

returns the task-id of a virtual task which represents the task on the far node.

There is a virtual task created at each node. You many now refer to the vid as
though it were a local task, sending to it, receiving from it, etc... The operating
system will ensure that all requests will be transparently sent over the network.

The virtual circuit provides the necessary mapping between two tasks. It also en¬
sures that resources can be cleanly recovered across the network when a task dies.
For example, assume that TASK A is a very nosy task and opened files on a large
number of different nodes and being an irresponsible task, killed itself without
closing any of its files. Upon the tasks death, the local task administrator would
examine the virtual circuits set up by TASK A and send control messages to the
destination nodes killing the virtual tasks at the other end. The death of these
virtual tasks will be perceived as the death of TASK A to the remote tasks. They
will then clean up in the same manner as the death of a local task, closing off
TASK A’s files. Without the virtual circuit, the death of any task would have to be
sent to every task on every node in the network just to be safe! This action would
bring a local area network to it knees.

If the poller is running and a node crashes, all nodes will be informed. They will
check if any of their tasks have a virtual circuit setup to the crashed node. If they
do, the local virtual task is killed and again the local tasks will perceive the death
of the remote task on the crashed node.

10.3.2 Ports

Ports provide the important capabilities of

- interrupt handler communications

-simple non-blocking communication

as well as the less important capabilities (due to names and messages) of

QNX too

Tasks

- identification of unrelated tasks on the same node
* - semaphores

10.3.2a Identification - single node only

Knowing die identity of another task gives a task the ability to communicate with
it. The task identities of the system tasks are fixed and thus known to all tasks.
When a task creates a new task (son), both the father and the son are informed of
each others task identities. In each of these cases the knowledge of identity enables
communication by messages. The above message primitives do not satisfy the
requirements of communication between unrelated tasks.

A port is a globally known name to which a task may attach in order to com¬
municate with unknown tasks. QNX provides a minimum of 32 ports which are
identified by number. The first 16 are reserved by the operating system of which
the first eight are privileged. A task may attach, detach or obtain the identity of a
task connected to a port. The following table summarizes die the action of die
attach and detach primitives on a port. For each primitive the port may be free or
already attached by another task.

PORT IS FREE PORT ALREADY ATTACHED

ATTACH return zero return task identity

of attached task

DETACH return zero return task identity

of attached task

Attaching to a free port claims the port, while detaching from an owned port frees
it. Detaching from a port you do not own will return a value as above but it will
not detach another task. It can therefore be used to obtain the identity of a task
connected to a port.

In the database example above, the database administrator would immediately
attach to an agreed upon port. All tasks wishing to communicate with it would
detach that port to obtain the task identity to which they must send.

The use of ports for name serving is only suitable on a single machine. Under the
network version of QNX the section on NAMES provides a better mechanism for
' identification which will work on a single machine as well as a network.

QNX Tasks

QNX 101

The major purpose of ports is to allow interrupt handlers to communicate with
tasks. The interrupt handler signals a port which a task as attached to. The signal
will wake the task up allowing it to process the interrupt.

10.3.2b Semaphores

The operations of ATTACH and DETACH implement a semaphore which may be
used to gain controlled access to a resource. QNX’s LIST command currently uses
port 16 to gain access to the line printer. In a multi-tasking and multi-user system
it is quite possible for several instances of the LIST command to be invoked con¬
currently. If they each wrote indiscriminately to the printer, you would end up
with an intermixing of output. Instead, the LIST command attempts to attach to
port 16 before opening the line printer for output. If successful, the LIST com¬
mand continues and starts outputting to the printer. If unsuccessful, then the
printer is already in use by another task. In this case the LIST command sends a
message to the LIST task which owns the port. Since LIST never does a receive,
the sending LIST will block. When the attached LIST finishes and dies, it is de¬
tached from the port and all tasks send-blocked on it are unblocked. The sending
LIST(s) will then again attempt to attach to the port. The code in LIST to imple¬
ment this consists of 2 lines of C code.

These semaphores will only work on a single machine and not across a local area
network.

10.3.2c Signals

A task may SIGNAL a port resulting in that port sending a message to the task
attached to it. This form of communication is special in that

1. The task performing the signal does not block.

2. The message sent by the port contains no data.

3. The signal may be performed by an interrupt
handler.

4. Messages sent by ports are queued ahead of
regular messages and will be received first
even if sent second.

The first point permits a form of non-blocking communication. The task as¬
sociated with the port will receive the message when it does a RECEIVE operation
from anyone or an AWAIT operation on a specific port. The task identity returned
by the receive will be that of the port and is clearly distinguishable from any task
identity. If a task sends multiple signals before they are received, they will all be
remembered. The conditional signal (CSIGNAL) will not signal a port if there is
already a pending signal.

QNX102

Tasks

The identity of the port which sent the signal is the only information which the
attached task receives. It is not even aware of the task which performed the sig- .
nal. This is much more limiting than the SEND primitive but adequately serves the

purpose of informing the task that a particular event has occurred. For example, if
a task was waiting upon the event of a game paddle switch being closed it could
attach itself to a port and wait for a signal from that port. The signal would in¬
dicate the event. No extra data is necessary.

Point three allows interrupt handlers to inform tasks of external hardware events.
The game paddle example above would signal the event within the interrupt han¬
dler causing the task responsible for that piece of hardware to unblock and service
it. The device administrator and file system administrator are both informed by
signals when a line is available or a disk operation has completed.

The final point simply gives communication by signals priority over that by mes¬
sages. When used in conjunction with signals from interrupt handlers, this gives
hardware events priority over software requests from other tasks.

10.3.3 Exceptions

So far, all communication between tasks has been synchronous with the receiver.
The receiver explicitly had to perform a receive operation and thus was expecting a
communication. Exceptions on the other hand are asynchronous with the receiving
task. They are usually generated by some abnormal event and may occur at any
time during the task execution. The best example is the exception associated with
a keyboard BREAK. When you run a program, you may type a keyboard BREAK
(Ctrl Scroll Lock on PC keyboard) at any time. This has die effect of setting an
exception on the task associated with the keyboard. There is NO way for the task
to know if or when the exception will occur. If the task has not protected itself
against this exception, then the default action is to kill the task.

There are a total of 32 exceptions which you may set on the task. These corre¬
spond to bit positions within two 16 bit words. The operating system reserves the
first 16 exceptions. User tasks may freely choose meanings for the second 16
exceptions. Those currently defined by the operating system are

QNX Tasks

QNX103

EXCEPTION HEXADECIMAL VALUE
modem hangup 0001

keyboard break 0002

quit 0004

communication error 0010

missing shared library 0040

floating point error 0080

kill 0100

memory violation 0400

privileged 0800

alarm clock 2000

task termination 4000

divide by zero 8000

The ’kill’ and ’task term’ exceptions may not be protected against and always

results in the task being killed. The ’task termination’ exception is the means by
which a task terminates itself (normally or via an explicitly coded abort).

Certain tasks, like the editor, do not want to be destroyed by exceptions like
BREAK. Therefore, the operating system provides the ability for a task to either
ignore exceptions or execute a user provided routine to handle them. In the case of
the editor, it terminates the current operation and returns to command level. Note
that due to the asynchronous nature of an exception it is necessary for the editor to
protect itself by ignoring exceptions during certain critical operations. In these
cases the exception is left pending until the editor re-allows it at which point the
exception occurs. What the editor has done is to force synchronization of the ex¬
ception during these critical places.

The capabilities of user tasks handling exceptions is best described using diagram
10.3. For simplicity we will assume a single exception being set (one bit set in the
exception word).

QNX 104

Tasks

Diagram 10.3

The exception fields of PERMIT, ALLOW, PENDING and FUNCTION are all
maintained in the user task’s address space and may be manipulated directly.

From within a C program they are referenced as

extern unsigned Exc_permit[2], Exc_a!!ow[2];

extern unsigned Exc_pending[2] 5 Exc_bits[2];

The PERMIT field may be thought of as a bit mask against which an exception is
applied. If an exception bit is set where a permit bit is not, then the task is not
permitted to handle that exception and is killed (1). Once the exception makes it
past this first mask, it is applied to the second mask called ALLOW (2). If this bit
is clear then the task is not allowing this exception at this time and the exception
bit is placed in the PENDING field (3). No other action occurs. The task may
examine the pending field at any time in order to see if any permitted but disal¬
lowed exceptions have occurred. This allows the task to poll the bits at its con¬
venience. If all bits are disallowed then the bits can be treated as a 16 bit number
which can be set by another task. Finally, if the bit in allow had been set, then the
function whose address is in the FUNCTION() field would be invoked (4). In this
case if there is not a function set up to handle the exception, the task is killed (5).

It is possible for multiple exceptions to be set upon a task by setting more than one
bit in the indicated exception. The above explanation operates on all 32 bits in
parallel. Killing the task (no permit) followed by invoking the exception function
(an allow) take precedence when considering multiple exceptions. The operating
system tasks do not set multiple exceptions on a task.

QNX Tasks

QNX105

The following table summarizes the actions for a single exception, permit and
allow, bit path.

PERMIT ALLOW

ACTION

clear

kill task

clear

set

kill task

set

clear

set proper pending bit

set

invoke exception function

If a task sets an exception on a virtual task (vc_create), the operating system will
forward the request to the node which contains the real task. The real task will
have the exception placed upon it.

A word of warning... If an allowed exception occurs, the task will become UN¬
BLOCKED before executing the exception function. This has the unfortunate side
effect of causing errors if the program was waiting for input from the keyboard for
example. User programs which handle exceptions should be prepared to handle
errors at any point in their program. Please refer to the documentation on the C
library routine EXC_HANDLER.

10.4 Global Names

As stated earlier, for a task to communicate, it needs to know the task id of the task
it wishes to communicate with. QNX offers a mechanism where a task may attach
a symbolic name of up to 8 characters which may be queried by other tasks. As¬
sociated with the name will be the node number and task id of the attaching task.

A task may attach its name as local to a single machine or global across the entire
network.

The first type of attaching is handled by a table in the local task administrator. The
second type is handled with the assistance of a server task which must be running
on a node in the network. This is described in the technical note "Attaching and
Locating Task Names" in the C binder.

Attaching a name is similar to the attach and detach primitives on ports.

10.5 Task States

The previous sections have talked about tasks blocking. In QNX a task is always
in one of six states.

DEAD - . - Task does not exist or is

being killed

READY - Task is ready to run

SEND BLOCKED - Task has done a SEND which

QNX 106

Tasks

RECEIVEJBLOCHED
REPLYJBLOCKED
HELD

NETWORK JBLOCKED

has not been received

Task has done a RECEIVE with

no waiting send

Task has done a SEND which has
been received but not replied to
Task is ready but has been
explicitly held

Task is blocked on a network
request

The three blocked states are all tied to the message communication primitives. The
state of HELD indicates that the task is ready to run (not blocked) but is being
prevented from running due to a HOLD operation on it. Performing a hold on a
blocked task does not change its state. However, as soon as the task unblocks, its
state will change to HELD, not READY.

The highest priority task that is ready will be the task which is running. If there is
more than one task ready at the highest priority level, then they will be time-sliced
every fraction of a second.

The possible state changes are indicated graphically in diagram 10.4. Hie arrows
indicate’ a state- transition caused by the indicated reason.

L Task seeds message 4. Task waits for message

2. Target task receives message 5. Message received

3. Target task replies

Diagram 10.4

QNX Tasks

QNX-107

10.6 Task Ids

A task id consists of a 16 bit word in which the lower 8 bits is a task number and

the upper seven bits is a version number. Each time a task is created, it is assigned
the task number of a dead task and the version number of that task is incremented
by one. The version number ensures that a particular task number may be reused
128 times before reusing a given task name. The telephone company follows a
similar policy in not immediately re-using canceled numbers. By holding off on
reassignment, there is less possibility of someone phoning the old number and
getting an answer. Instead they get a number out of service. Similarly, in QNX, a
send to an old task will usually fail. The top bit indicates whether the task is local
or remote (virtual task).

The task number must lie in the range of 1 to 254. The maximum number of tasks
allowed and other system information may be obtained by using the TSK com¬
mand.

tsk info

Tne return values of system calls which return task names is summarized in the
following table.

MEANING
Task does not exist
Valid port name
Valid task name
System call failed

where xx is any combination (00 to ff) and
the top bit indicates if the task is
0 - local (real) task
1 - remote (virtual) task

0500 - port five

0508 - local task (number 8, 5th incarnation)
8728 - virtual task (number 28, 7th incarnation)

10.7 Task Hierarchy

Tasks running in the system have a hierarchical (tree) structure which very closely
parallels that of the file system. Each task has one father and zero or more sons
and brothers. Two examples are shown in diagram 10.5.

QNX 108

Tasks

doc playerl player2 player3

Diagram 10.5

When a task dies, all its children are also killed. This may seem harsh, but it is
necessary to maintain a consistent task hierarchy. Imagine removing a directory
without first removing the files under it!

10.8 Task Creation

When a task creates a son task, there are three major options available to it.

1. It may wait upon the sons death before
continuing to execute itself.

2. It may continue executing in parallel
with the son (concurrent).

3. It may continue to execute in parallel
with the new task but not preserve the
father son relationship (background).

As a result the death of the father
task will NOT kill the new son task.

The command interpreter (shell) by default always chooses option 1 unless you
explicitly tell it to run the task background (option 3). Option 2 is not a common
occurrence. One might imagine a large application program which consists of one
father task which creates several son tasks, all performing a separate function, and
running concurrently. Killing the father will remove (kill) all sons.

In addition the father task may also set the priority of the son at creation.

10.9 Terminal Ownership

At any one time, only one task is associated with a terminal. This will be the most
recent task to open the terminal for read. Besides receiving all input the task will
also catch keyboard BREAKS. Each open stacks on top of the last open. Only the
last open on the top of the stack is active. Closing a terminal will remove it from
the stack. This may move a previous open to the top of the stack making it active

QNX Tasks

QNX109

again. If a task which is not on top of the stack attempts to read from a terminal,
the request will be queued until that tasks open becomes active. A remote task
may take active control of the terminal by opening it in the same manner as a local
task. This scheme has no ambiguity.

When a task is created it may optionally be '’handed” down responsibility for hand¬
ling breaks on the device. It is possible for a son task to process data from a ter¬
minal, but have breaks still be set on the father task.

QNX110

Tasks

11. QUICS - The QNX Update System

The QNX update system, called Quics, is a computer which runs 24 hours/day
which you may call (using a modem) to:

• Download fixes and changes to the operating system, utilities

and libraries.

• Download a variety of free software from various sources.

• Send us electronic mail.

• Engage in a conference with other QNX users on a large
variety of topics.

The first point allows us to provide you with a level of customer service which is
second to none in this industry. For example, if you report a bug, perhaps in a
utility or library routine, you can often download a revised version within hours of
reporting the problem. We maintain on line, the most current versions of all
programs including the operating system itself for download. Along with these we
provide a list of all changes made to the system. You may wish to sign on once a
month and make a log of this list.

We also maintain a growing list of free software which may be of interest to you.

It includes games, nifty utilities and a megabytes of source provided by ourselves
and our customers. This source can be an invaluable aid in helping you to under¬
stand some of the intricacies of QNX. For example, the QUEUE manager shipped
in binary form with your system is available in full source under the free software.
The same is true for all disk and graphics drivers.

If you are not in a hurry for an answer you can send us electronic mail which we
will answer within a day or two.

Lastly, if you would like to comment or ask a question which you feel other users
may be interested in, then you will want to use our conference system. It has a
command structure which is very similar to that used by Byte magazine’s con¬
ferencing system. All the QNX developers are members of the conferencing
system as well as most of our more active developers. It is not unusual to pose a
question and have several comments on it within an hour or so. There are topics
on real time, hardware, utilities, c compiler,... and so on. You do not need to be a
QNX customer to use the conferencing system. It can be accessed from a terminal
or a terminal emulation program running under DOS.

The machine you are calling is node 1 ofa large QNX network. ■ It is our boot node
and the node from which most of our users get all their commands. While signed
on, you are in fact sharing the machine with quite a few users. At the time of this
printing the boot node is an 8 Mhz AT with 3 modem lines and an X.25 line into
the Datapac public network which supports 4 (expandable to 32) additional users.

QNX Quics

QNX 111

All three modems will support both 300 and 1200 baud service. We are always
upgrading our equipment and some (if not all) of the modems will support 2400
baud and we are looking to provide 9600 baud service as well. The 3 modems are
on a hunt group with the primary number being.

(613) 591-0934 • First number of the hunt group.

An up to date configuration on the number of modems, their types and phone num¬
bers is maintained on the update system. You can read this when you give us a

call.

As stated above, we are also connected via an X.25 link to the Datapac public
network. An X.25 card plugs into our AT and interfaces with X.25 software which
mns under QNX. The X.25 link can support several user calls at one time. To
connect with us via X.25 you will have to make a pre-paid call or register with us
for an X.25 account number allowing you to make collect calls. Our network
address is

3020 85701416

Our datapac address.

L Datapac’s network code.

11.1 How To Phone Us

To call us you will have to use one of QNX’s terminal emulation programs.

qtalk « A simple terminal program which comes with the system,
qterrn ® A very slick, full featured terminal program which is
separately purchased.

Since QTALK is shipped with every system we will describe how to contact us
using it. We will assume that your modem is connected to the QNX device
$mdm. If it is not, you will have to specify to QTALK which tty device it is on.

Step 1 Set your baud rate to conform to your modem as follows:
stty baud=2400 par=none bits=8 >$mdm

stty baud=1200 par-eene bits=8 >$mdm (QNX default at boot)

stty baud=30O par=none bits=8 >$mdm

QNX 112

Quics

Step 2 Start QTALK and cause your modem to dial us. If you are in north

america and have a hayes compatible modem you can use QTALKS’s
dialing directory capability. We provide an entry with our phone number
and the name "quics". Refer to the documentation on QTALK in the
utilities section of the operating system manual for mote information.

qtalk quics [m-modem__device] ® Hayes compatible modem,,
qtalk [m~modem_device] © Other modem,,

The option m -modemjievice is only necessary of your modem is not
connected to the device $mdm.

Step 3 When the word CONNECT is printed, wait one second. If you do not get
a login message type the following 5 characters

&b„caniagerretum

L this is the <enter> key

and repeat if necessary. You should get a screen of information telling
you what to do next. One of your options will allow you to download an
up-to-date manual on how to use Quics, the update system.

11.2 X25 Access

Quics is also connected to the Datapac packet network via an X.25 link.

Customers may access the system by using a public dial-up port. Instead of
placing a long distance phone call directly to one of QNX’s modem lines, you
place a local call to a modem line on a packet network. Once connected to the
packet network you will have to place a call to QNX’s X.25 link. This is accom¬
plished by entering a multi-digit number (referred to as a DNA, destination ne¬
twork address) to identify who you wish to call. Once a successful call is made,
you will be connected to QNX’s update computer and all data will be routed
through the packet network. Each country tends to have its own packet network
with gateways connecting the many networks. Due to agreed upon standards, you
should be able to access our update computer from nearly any country/network in
the world. The standards, unfortunately, do not apply to the user interface pre¬
sented to the user when he wishes to place his call. At this point, you are com¬
municating with the network ( this is similar to the method by which you com¬
municate with a hayes modem when you wish to place a call) and each network has
it’s own command language. Once die call has been established you are then
communicating with QNX and the network should pass all data transparently.

There are two major advantages of accessing the update system via X.25.

QNX Quics

QNX 113

First, the networks communicate at very high speed and pass data to each other in a
completely error-free manner. The only place a communication error is possible is
between your modem and the network’s modem over the phone line on which you
called. This will typically be a local phone call. Those of you who have tried to
access the update computer directly using long distance may have discovered that
the lines are often very noisy. It seems to depend on the time of day, phase of the
moon and how badly you need the data. Our European customers have found the
long distance line pretty much unusable. Our X.25 link has changed all this and
for the first time we have a global update system.

Second, access via the packet networks is often cheaper than the cost of a long
distance phone call. This is especially true when you consider the re-transmission
time caused by data errors. The cost is based upon both connection time and the
amount of data transferred. Each network has it’s own rate schedule with some
networks being more expensive than others. The different networks have agreed
upon inter-network costs in much the same fashion as the international phone
companies.

You still have to use a QTALK or QTERM to contact us as: described above,,

however, you will call your local public network and then use it’s commands to
place a call to us.

Contact QNX Software Systems Ltd’s marketing department for an application for
an X.25 account which will allow you to place collect calls.

QNX-114

Quics

12. Tips on Using QNX

This section consists of a few tips in getting started on QNX.

12.1 Memory Requirements

To boot QNX you need a minimum of 256K of memory. This can be expanded to
640K in real mode and 15 Megabytes in protected mode.

12.2 Enabling Colour

You may change the colour of your text and screen by issuing escape sequences to
your screen. As an example, the sequence

Esc@71Esc!71 (Esc is the single Esc key)

will set your character and fill attribute to white on blue.

COLOUR CODES

digit

colour

digit

colour

black

red

blue

magenta

green

brown

cyan

white

You should set your colour preference using ESC @ and ESC ! in your sysinit file
and follow it with an ESC S to save it away. All QNX applications which play
with the colour will print an ESC R to restore the saved colour before exiting.

type Esc@l\Esc\l\EscS (Esc is the single Esc key)

12.3 Disabling Colour

If you have a colour card, but a black and white monitor, you may wish to suppress
all colour since it makes text very hard to read. You can disable colour using the
stty -f nocolour command.

12.4 The Mount Command

The MOUNT command allows you to dynamically reconfigure QNX. You may

1. Install custom disk drives.

2. Install consoles.

QNX Tips

QNX 115

3. Install shared libraries.

4. Install disk caches.

By default QNX assumes a 360K (40 track) floppy disk drive for drive one and the
same for drive two if it exists. On machines like the AT, QNX will automatically
configure itself to support the 1.2M high capacity drives. On a PC, users may have
an 80 track floppy for drive 2. To configure your 80 track drive, you would issue
the command

mount disk 2 t=80 n=9 h=2

If you can spare the memory, a great improvement in hard disk access time can be
made by installing a disk cache. For example, we could add a cache to disk 3 by
issuing:

mount cache d=3 s=32k

If you are going to accessing large files in a random access mode (data bases), then
a tremendous improvement in performance can be had by mounting an XCACHE.
A file in QNX consists of one or more extents. Each extent is a contiguous series
of blocks within the file.

extent 1 extent 2 extent 3

An XCACHE caches the information on how these extents are connected. This
saves you from having to chain through extents when seeking within a file. Each
extent connection requires 20 bytes. This cache is shared by all disks.

mount xcache s=10k -enough for 512 extents

Finally, you can speed up disk writes by mounting a bitmap cache. This cache
takes up very little room and yet it can add significant performance when growing
files.

mount bmcache d=3

Virtual consoles an extremely useful extension to QNX and can be added to the
system (at the expense of another device entry which is hopefully not required) by
a command such as:

QNX 116

Tips

mount console coni

Shared libraries such as graphics libraries or floating point math libraries can be

installed with commands such as:

mount lib /drivers/glib.ega
mount lib /config/qdb.slib

The use of shared libraries allows application programs which run under QNX to
be independent of hardware.

12.5 Ramdisk

One form of the mount command allows you to create a virtual disk in memory.
This disk behaves exactly like a real disk in all respects except speed where it is
much faster. To create a 200K ramdisk as drive five issue the command

mount ramdisk 5 s=200k

The ramdisk loads a driver into memory. As a result, the above command would
require just a little bit more than 200K of memory to create the ram disk. You can
only mount a single ramdisk.

You must now initialize the disk using the dinit command as follows

dinit 5

QNX will not look on the ramdisk until you include it in its search order using the
search command

search 5 3

hi this example we have indicated that we wish to always look on the ramdisk first,
followed by drive 3. We will not look on drive 1 unless that drive number is ex¬
plicitly prefixed to the file name (1:/).

Once the ramdisk has be initialized you may create directories and files on it.
Creating the directory /Imp on it gives you a place to put all temporary files you
wish to go away when you power off. The compiler places it’s temporary files
under /tmp as well.

mkdir 5:/tmp
chattr 5:/tmp p=+c

QNX Tips

QNX 117

Don’t forget to add general create permission on the /tmp directory if other users
are going to be using temporary files. Ramdisks may be reinitialized by using
DINIT and starting again! If you have sufficient memory, you may wish to create
a larger ramdisk and place a /cmds directory on it. Copy down the editor and its
macro file as well as any other commonly used commands.

cp 3:/cmds/ed 5:/cmds/ed
cp 3:/cmds/ed.macros 5:/cmds/ed.macros
„ oe any other commonly used commands ...

Ramdisk is also convenient for data logging over a high speed communication
line. The pause going to a disk is eliminated.

Once they get used to the speed, most users find it hard to work without a ram¬
disk! A ramdisk can be created from your sys.init.nn file.

12.6 Shared Libraries

Rather than duplicate code in many applications, or increase the size of the
operating system, QNX has adopted the technique of dynamically mounting
software libraries of code which can be shared. This technique can also be used
provide machine independent interfaces to hardware. For example, a different
Graphics library may be mounted for each type of graphics card. The user’s ap¬
plication program does not change. It makes calls into the shared library to ac¬
complish a function. The standard shared libraries are.

/config/float.slib - software floating point

/config/float8087.slib - 8087 floating point

/drivers/glib.ega - Console/Graphics for ega card

12.7 Operating On Groups Of Files

QNX provides two very useful commands which allows you to execute a com¬
mand on a group of files. They are the EO (execute on) and WS (walk structure)
commands. These routines may seem confusing to the novice, however, they will
quickly become indispensible as you become familiar with the system. Please
keep them in mind and refer to the documentation in the utilities manual.

QNX 118

Tips

Appendix A

Character Set and Keyboard Codes

QNXTips

QNX119

ASCII Code to ASCII Character Table

Upper 4 bits

01 2 3 4 5 6 7

DLE

SOH

DC1

STX

DC2

' r

ETX

DCS

c ■

EOT

DC4

4 .

D -

ENQ

NAK

ACK

SYN

■

BEL

ETB

)

SUB

{

]

DEL

CONTROL CODES

NUL - Ctrl §
SOH - Ctrl a

STX. - Ctrl b

ETX - Ctrl e
EOT - Ctrl d
ENQ - Ctrl e
ACK - Ctrl f
BEL - Ctrl g

BS - Ctrl h

HT - TIB
LF - Ctrl j
VT - Ctrl k
FF - Ctrl 1
CR - Enter

50 - Ctrl n

51 - Ctrl o

OLE - Ctrl p
DC1 - Ctrl q
DC2 - Ctrl r
DCS - Ctrl s
DC4 - Ctrl t
MftK - Ctrl u
SYN - Ctrl v
ETB - Ctrl w

CAN - Ctrl x
EM - Ctrl y
SOB - Ctrl z
ESC - ESC
FS - Ctrl |
GS - -Ctrl ]
BS - Ctrl A
US - Ctrl

QNX Keyboard Codes

Upper 4 bits

Shift

Ctrl

Alt

TAB

Home

Boom

Shift

Ctrl

Alt

Shift

Ctrl

Alt

Fgup

PgUp

Shift

Ctrl

Alt

minus

C ,

Shift

Ctrl

Alt

F10

left

Ctrl

Alt

five

Ctrl

Alt

right

Ctrl

Alt

plus

Ctrl

Alt

End

. X

Ctrl

Ctrl '

Alt

down

Ctrl

Alt

F10

PgDn

Shift

Ctrl

Alt

Ins

Shift

Ctrl

Alt

Shift

Alt

Del

F12

Shift

Ctrl

Alt

PrtSc '

PrtSc

Shift

Ctrl

Alt

F10

Fll

Shift

Ctrl

Alt

TAB

F12

F12 *

Note:

The above codes are preceded by a hex FF code, if the option EXPANDJFUNC is turned on, and the indicated

function keys are pressed.

The above codes can also be generated as a compose character, which results when the ALT key is pressed and
released, then 2 more characters are typed, compose characters are NEVER preceded with an FF code.

Alt C
Alt u

Alt e
Alt a
Alt a
Alt a
Alt a
Alt c
Alt e
Alt e
Alt e
Alt 1
Alt 1
Alt i
Alt A
Alt A

Alt *
Alt +
Alt >
Alt <
Alt -
Alt ~
Alt o
Alt .
Alt s
Alt g
Alt *

Alt

E '

Alt

✓

Alt

A e

Alt

A E

Alt

o *

Alt

o "

• •

Alt

-•w

Alt

o '

Alt

u *

Alt

u '

Alt

y "

Alt

0 "

• m

Alt

u M

• m

Alt

-f

Alt

c |

Alt

L -

c£

Alt

J /4

Alt

Y -

Alt

P t

Alt

f -

Alt

a OC

* r

j 77

e Z
s O’

u y

t T
I §

- e
w n

* S

/ <t>

u n

Release Alt before typing 2 character
Input sequences

AT disk 10

Alive 33

Argv 81
Attach 101
Attributes 69
BIOS disk 11
Background 83,109
Backslash 81
Backup 17
Bad blocks 16,17
Baud rate 38
Bios driver 19
Bitmap 62
Blocking 93
Bmcache 21
Booting

Sys.init 20
floppy 3
hard disk 18,20
network 31
COM1 37
Cache 21,116
Carrier detect 43
Cd 67

Change directory 89
Characters, foreign 45,48
Chattr 73
Colour 115
Comm 41,43
Command files 86
Command interpreter 79
Communication 95
Compose characters 45,48
Concurrent 109
Conference system 111
Configuration, os 27
Consoles

colour 115
graphics 58
memory 55

mounting extra ones 55

Ctrl-z 48

Current directory 67,77,89

DCE/DTE 39

Datapac 112

Date 3
Dcheck 17
Death 99,100,109

Detach 101
Device
editing 41

escape sequences 50
input 45
input gate 49
line editing 46
line recall 49
output 50
smartcards 44
type-ahead 46
Device admin 94
Device names 73,74,78
Devices 45
Dinit 16
Directories
moving up 68
Directory 62
changing 67
current 67
number files 62
printing 68
structure 62
Disks 7
at 10
bios 11

booting 3,18,20
booting from 18
cache 21
controller 7
drivers 7
formating 15
hdiskxfg 19
installation 12
mounting 8,14
nighthawk 11
partition 12,14
ps/2 11

second physical 27
xt 9

. Dmark 16
Dos partition 13,26

Index

Download 111

Drive numbers 66

EGA

smart cards crashing 57
switching consoles 57
Ega117

Exceptions 95, 103
actions 106
catching 104, 105
list of 103
network 106
Execute permission 88
Fdformat 15
Fdisk 14, 20
File admin 94
File system
attributes 69
bitmap 62
commands 65
current directory 67,77
device names 73
directories 62
drive numbers 66
file names 61
max file size 61
network 75
network access 78
node numbers 75
pathnames 65
permissions 69, 73
ramdisk 117
remdisks 77
search order 66, 75
structure 61
text files 41, 61
user numbers 73
Flashing text 51
Flow control 41
Foreign characters 45, 48
Free software 111
Graphics

Libraries 58
consoles 58
Group 73

Group permissions 69

Hard disks
see Disks 7
Hdisk.cfg 19
Hierarchical 62
Highlighted text 51
Input 45
Installation
command 5
manual 7
network 29
summary 22, 32
Inter-task communication 95
Interrupt handlers 103
Inverse text 51
Keyboard
input gate 49
line editing 46
line recall 49
shift keys 45
type-ahead 46
Kill_vcs 33
Line editing 46
Line recalling 49
Locker admin 95
Login 3, 42
modem 42
Macros 86
Member 73
Memory

Requirements 115
Used by consoles 55
Message deadlock 98
Message example 98
Message queuing 98
Messages 95, 96, 99, 100
Mkdir 73
Modem 42
Modems 37, 41
Mount 115
consoles 55
Multi-tasking 93
Multi-user 93
Nacc 30, 78
Names 106
Netboot 31

Index

Netboot directory 18
Network 94

access 30,78
booting 31
diagnostic tips 35
exceptions 106
hardware 29
installation 29
installation summary 32
messages 99
poller 32,100
Network admin 94
Nighthawk disk 11
Node numbers 30, 75
Nodes 85
Non-blocking 102
Null modem 39
Or-bar 84
Osconfig 27
Other permissions 69
PS/2 disk 11
Parallel 43
Parity 38
Partition 5,12, 14
dos 26

more than one 26
Passwords 31,73
Pathnames 65

absolute 65,66,67
network 75,78
relative 67
Patterns 82
Permissions 69, 73
access chart 69
default 71,72
examples 72
types of 70,71
Phone numbers 1,112
Pipes 84
Poller 32,100
Port

ids 108

Ports 95,100

identification 101
interrupt handlers 101,103

semaphores 102
signals 102
Printer 41
Printers 37, 43
Priority 83, 89, 93
Pwd 68

QNX loader 18
QNX partition 12,14
QUICS 111
Qtalk 43, 112
Qterm 43
Queue admin 95
Quics 111
phone numbers 112
x.25 113
RS-232C
see serial 37
Ramdisk 117
Rebooting 48
Receive 96
Record locking 95
Record separator 61
Redirection of I/O 80
Remote Disks 77
Remote execution 85
Remote search 75
Reply 96
Root 62, 65
Scheduling 93
Screen

colour 51, 52, 53
cursor addressing 51
escape sequences 50
Search 17
remote 30

Search order 65,66,76
example 76
indirect 76
remote 75
Semaphores 102
Send 96
Serial 37
4/8 port cards 38
baud rate, parity 38
cables 39,40

Index

coml, com2 38
flow control 41
i/o ports 37
interrupts 37, 38
login 42
modem 42
modems 41
outgoing calls 43
printer 41
problems 43
ps/2 38
smartcards 44
Server 98
Setvar 87

Shared libraries 118
Shell 79

Variables 86, 87
background tasks 83
command files 86, 88

uuimiiailuS Cty

comment lines 85
multiple commands 84
pipes 84
prompt 79
quoting 81
redirection 80
reference chart 90
remote execution 85
sys.init 80
useage message 83
variables 86
wildcards 82
Signals 102
Smartcards 44
Spooldev admin 94
Standard I/O 80
Star 82
States 106
Stty 38

Super user 4,73, 83
Sys.cfg 27
Sys.init 30

Standard I/O 80
sample contents 20
System tasks 94

Sytem initialization file 30
Task

. background 83

code sharing 89
communication 95
creation 48,109

death 99,100,109
exceptions 95, 103,104

hierarchy 108
ids 108

messages 95,96,97,98,99

names 106

ports 95,100,102
priority 83, 89, 93

scheduling 93

states 106,107

system 94,95

tty 109

virtual circuits 100
Task admin 94
Technical support 1
Terminals 109
Text files 41,61
Time slice 93
Timer admin 94
Tips 115
Tree structure 62
Underline text 51
Update system 111
Usage message 83
User directory 62,73
User numbers 73
Variables 86, 87
Vc_ereate 100
Virtual circuits 100
Warm boot 48
Wildcard 82
X.25 111, 113
address 112
phone numbers 111
XON/XOFF41
XT disk 9
Xcache 21

Index

QNX Utilities

QNX is provided with a variety of utilities which aid in the management of files,
the creating and formatting of diskettes, communicating with other computers, etc.

The following pages describe the standard QNX utilities and how to use them.
Each utility will be described separately, starting with a brief description of the
command syntax, followed by a list of all possible options and a few examples.
The command will then be described in more detail. References to other similar or
related utilities may be included.

In the following pages, the syntax of a utility may include a few of the following
characters:

[.„] - Square brackets are used to indicate OPTIONAL

fields or arguments.

| - OR bar is used between ALTERNATIVES, one of which

must be selected.

* - Asterisk following an argument indicates that a

REPETITION of that field is also allowed.

Any arguments which contain boldfaced characters may be abbreviated to the
boldfaced characters alone.

Italics are used to represent data which the user must supply, such as a filename or

number,

A few examples are included with every utility to help make the syntax of that
command more obvious.

Command Summary

QNX is shipped with a rich variety of commands. It is well worth the time to look
through all of this section, reading enough about each utility to get a good feel for
what it does and when you would use it. This way, you will know what to look for
later, when you need to refer to the manual for the precise details on a particular
utility.

Learning the commands available on an operating system is one of the first tasks
which confronts most new users. Depending upon your level of experience, this
can be a slow process. To aid you in this respect we have listed most commands
by category. The most frequently used and needed commands are marked with a

star (*).

Communicate

COMM

- Modem communication handler

QCP

- QNX Communications Protocol

QTALK

* - Talk over Communications Line

STTY

* - Set TTY options

C mm mmti m

COMM

QCP

QTALK

STTY

- Modem communication handler

- QNX Communications Protocol

* - Talk over Communications Line

* - Set TTY options

Configuration Utilities

ACCOUNTANT

BOOT

CLOCK

CLRHOUSE

CRON

DATE

DEFJ5ERVER

DEFPIPE

FDISK

KBD

LOCKER

MOUNT * -

ONTTY

OSCONFIG

PASSON

QUEUE

RTC

SHARON/SHAROFF -

SLICE

TCAP

TIMER

TSET

TZSET

Accounting Task

Select an OS file for disk booting

Display Time and Date On Console

A distributed database and name server

Schedule commands in background

Display or set date and time

Define id of global name server

Define temp files for pipes

Create QNX disk partition

Redefine keyboard layout

Implement record locking in QNX

Mount disk drives, consoles or libraries

Create task on another tty

Change operating system parameters

Turn on password protection

Implement queued message passing in QNX

Get Date from Real-time Clock

Define or Query the Disk Search Order

Do/don’t share code segments

Set the timeslice rate

Manage terminal capability database

Implement timing facility in QNX

Set terminal type

Display or set timezone offset

Development Utilities
CC

DEBUG

LINK

MAKE

Compile Command (C, Basic,...)
Invoke the low level system debugger
Link object files
Maintain and recreate files

CfckMMlJfis

CHKFSYS

DCHECK

DCOPY

DDUMP

DINIT

DMARK

FDFORMAT

PARK

QUERY

- Check entire file system for consistency

- Check a disk for bad blocks

- Copy entire disk to a second disk

- Dump the contents of a disk block

- Disk Initialization

- Mark bad tracks on a disk

* - Format floppy diskettes

- Park the heads of a hard disk

* - Query the utilization of a disk

Editing and Word Processing
ED * - Full screen editor

LED - Line Editor

CHATTR

CHGRP

CHMOD

CHOWN

OREL

FREL

MKDIR

PWD

RMDIR

ZAP

* - Change current Directory

- Change Attributes of a file

- Change group (group number) of a file

- Change mode of a file

- Change owner (member number) of a file

- Release Directory

- Execute On a list of files

* - Release File

* - Make directory

- Print Working Directory

* - Remove files

- Remove directories

* - Walk directory Structure executing a command

- Zap damaged files out of existence

BAR

DUMP JOB M

Draw Bar Charts

Make a hardcopy of Graphics Screen

Information Handling

CRYPT

- Encrypt/Decrypt files

DIFF

- Difference between two files

DUMP

- Dump the contents of a file in hexadecimal format

EXPL

- Explain

GREP

- Search a file for a pattern

LOCATE

* - Locate patterns of characters in a file

* - Display a file or stdin by pages

MSORT

- Merge sort utility

PACK

- Pack a file to reduce its size

PATCH

- Patch files

SIZE

- Display the size of a file

SORT

- Sort files

SPATCH

- Full screen patch utility

UNPACK

- Unpack a packed file

- Word count

XLAT

- Translate Characters

I.istinp DirM'fnries and Fil PS

DIR

* - Display directory tree

FILES

* - List Files

FSTAT

- Display file status

* - List directory

MisMlanfigus User Commands

APB

- Send a Public Bulletin

BEEP

- Beep a user on another terminal/machine

BREAK

* - Break a task

CALC

- A simple calculator

- Execute a shell file

ECHO

- Echo arguments to standard output

KILL

* - Kill a task

* - Log-in to QNX

LOGOFF

* - Terminate a QNX Session

PATH

- Change command search path

PRI

- Set priority

PROMPT!

- Display tty number

PRTSC

- Print Screen

* - Execute Shell Commands

SLAY

* - Kill a task by name

SLEEP

- Sleep for a number of seconds

STYPE

- Type arguments on the terminal (no CR/LF)

TYPE

- Type arguments

MffldngJiMs

BACKUP

CAT

COPY

FBACKUP

SPLIT

TBACKUP

* - Backup Files to a backup diskette

- Concatenate input files into one larger file

* - Copy files

- Archive files to floppy disk(s)

* - Move files

- Split a file into one or more files

- Archive files to QIC60 tape(s)

Network QNX Utilities

ALIVE

KILLJVCS

NACC

NET

NETBOOT

NETSTATS

NETTEST

POLL

Set up/down status of a node

Kill all virtual circuits to a node

Set network access to disks, devices and CPU

Query machines on the network

Service boot requests from the network

Display network statistics

Check data transmission between two nodes

Poll nodes (network version only)

Printing Utilities
LIST

LPS

SPOOL

SPOOLDEV

List files on the line printer
Postscript Laser Printer Filter

Print file contents on terminal
Spool files to a printer
Create Pseudo-Printers

System Information

ACCSTATS

DOPEN

FOPEN

SAC

TSK

WHO

Print Accounting Statistics
Display open devices
Display open files

Display system activity at each priority level
Display task information
Who is logged-in to the system

ACCOUNTANT -Accounting Task

Syntax:

accountant [b=bufjimit] [ f=file_namel ] [f-filejiame2] [t-ttys]

[^verbose] &

Options:

b-bufjimit - Number of accounting entries to buffer before switching
to secondary file (if it was specified).
t-filejiamel - Primary file to save accounting entries in.
i=filejiame2 - Secondary file to save accounting entries in.
i=ttys - List of tty’s to gather accounting information on.

+'verbose - Print each loginAogoff on the screen.

where: ttys = ttyj'ange[,ttyjrange\

ttyjange = ttyjtum[:tty_num]

Examples:

accountant &
accountant t=0,2,3:6 &
accountant f=3 :/accounting/log &
accountant f=3 :/accounting/logX &

accountant f=3 :/accounting/logX f=[4]3 :/accounting/logX b=50 &

Description:

ACCOUNTANT is a task which runs in background and collects accounting
information from the QNX TASK administrator. In a local area network you must
run ACCOUNTANT on each node for which you wish to collect accounting
information. If you do not specify which tty’s to gather information on, then
information will be gathered on all tty’s.

Accounting information is generated on each login and logoff of a user. Each
accounting entry is 48 bytes long and contains the following information.

struct accstat__entry {

char accsjype; /* O-Not Used 1-Login 2-Logoff >3-User defined */
char accstty;

Utilities

[ACCOUNTANT]

ACCOUNTANT

unsigned accsnid;
char accsgroupnum;
char accsjiserjnum;

unsigned accs_tlme[2];
char accs_name[16];
char accs_spare[48-16-4-6];

};

This program may be run in one of two modes, file mode or buffered mode (the
default).

FILE MODE

When you specify the name of a file using the f-filename option, accounting
information is immediately written to the file. If the filename ends in a capital X,
the X will be replaced by the year and month (eg: 8701 for January 1987). For
each record written the file is opened and closed. If the file is busy,
ACCOUNTANT will retry the open 10 times. If that fails it will buffer the
information in memory. This procedure is followed for each accounting entry
received. When the file is successfully opened, all buffered accounting entries will
be written. There is room for about 1000 buffered entries, after which any new
ones will be lost.

If you have specified a secondary filename, ACCOUNTANT will switch over and
attempt to use it, after buffering a certain number of accounting entries. This limit
defaults to 100 but may be changed using the b -buffer Jimit option. If you specify
two files, any program which prints reports will have to read from both files
removing accounting information in time order. ACCOUNTANT’S ability to
buffer entries in memory allows a reporting program to open the file for read
(which locks out ACCOUNTANT), while it generates it’s report.

Adding a single record to the end of a file would result in a very fragmented file
over a long period of time. To reduce this fragmentation, ACCOUNTANT will
pregrow the file by 200 accounting entries each time the file becomes full.

—

l_i_

lT_i

L_i_J

_5_ 1

o..pregrown...

The first 4 bytes of record 0 contain the number of valid
data records (as a long). Use fget(&lval, 4, fp) in C.

The first accounting entry starts at record 1.

The end of the file is pregrown with zero’s.

[ACCOUNTANT]

Utilities

ACCOUNTANT

BUFFERED MODE

If you do not specify any filenames on the command line, ACCOUNTANT will
buffer all accounting entries. In this mode the b= option (if present) is ignored. To
collect the accounting information you must write a program which sends
messages to ACCOUNTANT, requesting the buffered accounting entries. The
message consists of a single byte containing a message code of 3. The reply will
consist of a msg_type followed by a 48 byte accounting entry.

struct useraccsjtnsg {
char msgtype;

struct accstatentry accs data;

*}5

The the msg_type will be one of the following:

Accs type

Reason

Data returned ok.

No more buffered accounting entries.

-2

File mode, not buffered mode is running,

-3

Unable to save request.

Bad message code in msg.type field.

ACCOUNTANT registers the local name "account". This allows a task in a local
area network to find and poll each ACCOUNTANT in the system.

In both file and buffered mode, a task may send ACCOUNTANT 48 byte
accounting entries. The msgjype code should be a 2 and the accs_type code must
be greater than 2. These are written to the file or buffered depending on the mode.
This allows special login/logoff programs to add extra accounting information.

The accs_date field is always filled in by ACCOUNTANT. All other fields are left
untouched.

See Also:

ACCSTATS

Utilities

[ACCOUNTANT]

ACCSTATS - Print Accounting Statistics

Syntax:

accstats file ... [t-ttys\ [u -userid] [-stats] [-verbose]

Options:

t-ttys - Only print accounting information on these ttys,

ii -userid - Only print accounting information on this user.

TTie userid may be a pattern.

-status - Suppress the status information.

-verbose - Suppress the printing of each login/logoff.

where: ttys = tty jange[,tty jange]

ttyjange - ttyjium [: ttyjium]

Examples:

cd /acclogs
accstats *

accstats 8701 t=0,2,3-6
accstats 870[1234] u=dtdodge

Description:

ACCSTATS is a utility which will print a summary of the accounting information
saved by the ACCOUNTANT program. The above examples assume that file
names are in the form yearmonth. This is a standard option available with
ACCOUNTANT.

See Also:

ACCOUNTANT

[ACCSTATS]

Utilities

MJV

■

ALIVE - Set up/down status of a node

Syntax:

alive [[+]nidjist]* [- nidjist ]* [b =nidjist]*

[a -nidjist]* [e=nidjist]* [n -targetjiode]

alive [+busy] [+up] [+down] [+newboot] [n-targetjiode]

WHERE

nidjist is nid_range[,nid_range[,...]]*
nid_range is nid[:nid\

Options:

+nidjist
nidjist
b =nidjist
a= nidjist

e-nidjist

+busy

+up

+down

+newboot

n -targetjiode

Examples:

These nodes are UP.

These nodes are DOWN.

These nodes are BUSY.

Allow these nodes network access
to this node.

Don’t allow these nodes network access
to this node (exclude).

Inform POLLER that this node is BUSY.
Inform POLLER that this node is UP.
Inform POLLER that this node is DOWN.
Inform POLLER that this node has booted.
Node on which to change up/down
status (default: this node).

alive - Display current up/down status of all

nodes.

alive n=3 - Display current alive status of node 3.

alive +2 - Node 2 is up.

alive “5,6,7:12 - Nodes 5, 6 and 7 through 12 are down,

alive +2,3 b=6 - Nodes 2 and 3 are up and 6 is busy,

alive -2 n=10 - Inform node 10 that node 2 is down,

alive +n - Inform the POLLER that this node

has booted.

alive +b n=7 - Inform node 7 that this node is busy.

Utilities

[ALIVE]

ALIVE

alive e=l:10 a=7 - Exclude nodes 1 through 10 except 7.

The ALIVE command may be used to manually indicate to your local machine

which nodes are up, down or busy. This command should not be needed if the
POLLER is running.

The first form of the alive command will set the local up/down status, unless the
n= option is used. The second form will inform the POLLER by default unless the

n= option is used.

The operating system will not initiate any communications with another node
unless it thinks that node is UP.

When a node changes from UP to DOWN, the operating system automatically
releases any resources which were being used by tasks on that node (usually files),
and unblocks any local tasks which were waiting for messages from tasks on that
node. This cleanup does not take place on the transition from UP to BUSY, or
BUSY to DOWN]

BUSY status is useful to temporarily remove a node from the network without .
releasing any resources on other nodes. This might be done on a node before using
the debugger to prevent the POLLER from flagging the node as down.

alive +busy

When the debugging session has ended, the alive command can again be issued to
tell the poller that the node is now UP and ready to receive communications from
other nodes.

alive +up

When a node is first booted, it is usually a good idea to inform die poller that the
node is now up. The poller will then transmit this information to all other nodes in

the network. To achieve this, the following command can be included in the file

"/config/sysinit" for your node:

alive +n

The POLLER is responsible for scanning all nodes which are alive and ensuring
that they are capable of receiving communications. If a node fails to respond to the
poller in a reasonable amount of time, it is marked as DOWN and all other nodes
are informed. This has the effect of releasing any resources which this node may
have been using anywhere on the network.

[ALIVE]

Utilities

ALIVE

The a= and e= options inform the operating system on this node to prevent or
allow network accesses from the nodes specified in the list. This permits "clusters"
of nodes to co-exist on the same physical network without interfering with each
other. This facility also provides a measure of security on larger networks.

The ALIVE command only applies to the network version of QNX.

See Also:

KILLVCS

NACC

POLL

Utilities

[ALIVE]

APB

APB - Send a Public Bulletin

Syntax:

apb message

Examples:

apb The pizza’s here!!!

apb Cartridge disk two is now mounted!

Description:

The APB command will try to display a message on every terminal of every node
in a QNX network. Each user will receive the message at the next convenient
time. The SHELL will print the message, for example, just before it prompts for a
new command.

If another APB is sent before the first one is printed on a terminal, the second
message will replace the first message.

See Also:

BEEP

[APB]

Utilities

BACKUP - Backup Files to a backup diskette

Syntax:

backup srcjiirectory dest directory [options]*

Options:

c=0

€=1

C=X

di-date

g=group
m -member

l=levels

P =[ h ]pattern

pd =[ A ]pattern
s=[c][d][p]

t -time

4-all

4-before

- Copy only those files which have not changed since the last
backup.

- Copy only those files which have changed since last backup

(default).

- Ignore change status.

- Copy only files which have changed since this date. Date is
of die form dd-mm-yy (default date is 1-1-80).

- Copy only files which have the indicated group number
(decimal number from 0 to 255).

- Copy only files which have the indicated member number
(decimal number from 0 to 255).

- Specifies how many levels of the specified source directory
will be copied. Typically "1=1" is used to cause only the
files at the current level to be copied. This option is
particularly necessary when copying a directory to some
sub-directory of itself (default is all levels).

- Indicates that only files with names that match this pattern
are to be copied. Multiple "p=" options are allowed, in
which case files which match ANY of these patterns will be
copied. Also, if the pattern is preceded by an up-arrow ( A ),
then files which match this pattern will NOT be copied.

- Indicates that only directories with names that match (or
don’t match) this pattern are to be copied.

- Suppress the copying of the

date

permissions (includes group/user numbers)
and/or

clearing of the changed bit on source file.

- Copy only files which have changed since this time on the
given date. Time is in the 24 hour format: hh:mm:ss
(default time is 0:0:0).

- Equivalent to c=x

- Change the meaning of the date and time options to mean
before. The default is now or after. 4-newest

Utilities

[BACKUP]

BACKUP

-cdireetory

-cfile

-error

-pause

-verbose

■f write
-fquit

Examples

the destination file is newer than the source, then do not
copy; keep the newest of the two.

If the directory does not already exist on the backup disk,
prompt the user if he wishes to create it, skip it or retry after
changing diskettes. The default is to always create
directories as required.

If the file does not already exist on the backup disk, prompt
the user if he wishes to create it, skip it or retry after
changing diskettes. The default is to always create files as

required.

Suppress message and prompt upon error condition.
Suppress prompt (don’t pause to load disks).

Turn off verbose option. This stops the BACKUP command
from displaying the names of the files it is copying.
Overwrite READ-ONLY files as well.

Abort on error.

backup

3:/ 1:/ - Backup all files from drive 3 to drive 1 which

have been modified since last BACKUP.

3:1 h/ -cf -cd - Backup from drive 3 to drive 1. If files or

directories don’t already exist on drive 1, then
ask user if they should be created.

/user/joe /user/bilS +a s=c

- Copy all of joe’s files to bill’s directory
without changing the modified state of joe’s
files.

2:/dirl l:/dirl p=*.c p= A test.c 1=1

- Copy files under /dirl on drive 2 to the same
directory on drive 1. Only copy modified files
which end in ".c" except "test.c". Don’t copy
sub-directories.

3:/user [2]l:/user d=14-8-84 t=9:00

- Backup files from 3:/user to 1 :/user on node 2.
Copy only modified files which have changed
since 9:00 am on 14-Aug-84.

BACKUP provides a mechanism for backing up files. The decision to back up a
file can be based on a number parameters. The default is to backup only those files
which have changed since the last time backup was used. The d=, g=, m= 5 p=,
pd= and t= options are by default don’t care conditions.

[BACKUP]

Utilities

BACKUP

Typically, a user will use the BACKUP command to copy all of the files which he

has changed onto a backup diskette. This eliminates the need to copy every file
onto the backup diskette at the end of every session. Only die changed files are
copied, which can be far less time consuming than an entire disk copy. This also
allows selective files or directories to be restored from a backup diskette. The
date, permissions and owner are be default copied to the backup files. The LS
command can be used to highlight those files which have been modified since the
last backup.

Is 4-modified

As an example of using the BACKUP utility, consider a user who is developing a
rather large application consisting of several C source programs. These programs
may all reside on one disk under a directory called "/work". During the course of
his day he will change many files, and create several object files as a result of
compiling these files. The object files need not be backed up since they can always
be created again from the source files. If he uses the naming convention that all C
source programs end with M .c M , and all object files end with M .o", the user could
backup only his C programs by typing:

backup /work /backup p=*.c

The backup command will by default only transfer the files which were changed
since the last backup. After backing up each file, BACKUP will clear the modified
bit on the file. If you wish to save every file you may specify either m=x or +all.

BACKUP is also handy for copying entire directories (with the +a option) on the
same disk. In this case it is desirable to suppress the clearing of the modified bit
since you are using backup more as a move command than a backup command.

backup /dirl /dir2 +all s=clear

Filename patterns can be any valid filename, with the following "wildcard"
characters:

* will match any character^ or run of characters

? will match any one character

[ccc] will match any of the characters in the brackets

Some examples of filename patterns are:

p=*.* any file with a dot (.) in it

p=*.[ch] any file ending in V or V

p=?a any two character filename ending in ’a’
p=[abc]* any file starting with ? ayb 9 or V
p= A *„o any file which doesn’t end in to 9

Utilities

[BACKUP]

BACKUP

In cases where a directory is larger than the diskette, it is sometimes necessary to
backup the files to different physical diskettes. The p= option may be used to

select files.

backup /util l:/util p=[abcdefghijkl]*
backup /util l:/util p=[mnopqrstuvwxyz]*

Once you have created a backup disk the -cf and -cd options will then allow all
files to be backed up, prompting the user to insert the proper backup diskette as
required.

See Also:

COPY

FBACKUP

TBACKUP

[BACKUP]

Utilities

BAR - Draw Bar Charts

Syntax:

bar filename[field]* options*

Options:

field - Which field to plot.

-border - No border around the graph.

+grid - Draw horizontal grids.

+high_res - Use high resolution graphics mode.

+hres - Force to CGA 640x200,2 colour resolution.

+Hres - Force to EGA 640x350,16 colour resolution,

-legends - Don’t include legends.

+line - Plot line graphs.

+mres - Force to CGA 320x200,4 colour resolution.

+outline - Draw outlines around each bar.

-relative - Don’t draw relative to baseline if
b= option is specified.

+shade - Shade bars instead of fill in colour.

+vstack - Stack bars vertically.

-ylabels - Don’t draw labels on the y axis,

a =char_angle - Angle of label characters (degrees)
b -baseline - Draw a baseline at this value. Bars

will be drawn relative to this line
unless -r option is used,
c ^colours - Only use this many colours,
f =field - Which field of the current file to plot,

g =gridscale - Only use this many colours.

l=labels Jile - Label x axis with labels in this file.
m-graphmode- Graphics mode to use.
p =printjomd - Create hard copy printout via this
command.

t=text - Label the Plot with this title.

x=xsize - Limit x axis to this size.

y =ysize
n=legendn

Limit y axis to this size.

Replace legend n with this name.

(eg: "l=sales" "2=1985 YTD")

Utilities

[BAR]

bar graphl

bar apples peaches pears
bar pigs cow sheep +v +H +s

bar sales l=months

bar plotl -y -1
bar 1985 1986 b=37 0 6
bar tl t2 13 b=10.0 +r

bar data,l data 9 2 data,3 +1
bar test "p=dump_ibm [2]$lpt !

Plot data in graphl
Plot side-by-side
High resolution shaded
plot stacked vertically
Plot with labels on the
horizontal axis.

Plot with no labels or legends.
Plot 2 files with a baseline
Plot 3 files showing deviation
from a baseline.

Line graph of 3 fields.

Plot graph and create hard
copy on node 2’s printer.

BAR is a business graphics utility which draws bar charts based on information in
one or more files.

BAR requires that a GRAPHICS LIBRARY and a FLOATING POINT LIBRARY
be mounted before using. The utility will determine the best dimensions and choice
of colours depending on the installed graphics library. Vertical and horizontal
dimensions can be reduced using the x= and y= options. BAR will attempt to use
the highest resolution mode which is supported by the currently mounted graphics
library. The +h, +m, and +H options can be used to force a particular resolution.
The m= option can also be used to force a resolution.

The information in each file is processed, using the FIRST field on each line of the
file (unless another field is requested). The remainder of the line can be used for
comments. The number of bars to draw is determined from the file which contains
the maximum number of lines. The width of each bar is adjusted automatically to
provide the best plot. The plot is automatically scaled in the vertical dimension to
accommodate the largest entry.

A border is drawn around the plot unless -b is specified, with appropriate grid
marks drawn on both left and right borders. The vertical axis is labeled
automatically with the minimum and maximum values unless -y is specified. If a
grid is requested (+g), then only the grid lines are labeled. The grid scale is
selected to best fit the data. Different grid scales may be chosen using the g=
option.

[BAR]

Utilities

BAR

The orientation of the label characters can be changed with the a= option, although
this is seldom useful.

Each graph is assigned its own colour where possible unless shading is requested
(+s), in which case each graph will be assigned a unique style of shading. The
graphs are plotted horizontally by default (normal bar chart) unless the vertical
stacking option is specified (+v) in which case the graphs are stacked on top of
each other. The scale will be adjusted automatically for vertical stacking. Negative
values are forbidden in vertical stacking mode.

Legends will be drawn on the bottom of the graph, unless the -1 option is used. The
legends can be customized using the 1=, 2= and similar options. If no legend is
specified, the name of the file will be used.

Relative plots with respect to a baseline are drawn if a baseline is given (b=) and
the -relative option is NOT specified. Relative plots show the bars as eitiier posi¬
tive or negative changes from the baseline. Relative plots are not allowed with
vertical stacking (+v).

The horizontal axis can be labeled by using the 1= option to specify a file
containing horizontal labels. This could be, for instance, a file consisting of the
months of the year. Extra elements in the label file will be ignored.

Line graphs are plotted if the +line option is specified. Dashed lines will be used if
+shade is also specified.

Hard copy can be obtained by specifying the name of a command which will make
a copy of the graphics device, once the plot is completed. BAR pauses when the
plot is finished, and if a command has been specified with p=, win call that
command if the user types the character p (for print). Any other character will
cause BAR to terminate without creating hard copy (see the last example).

Most of the command line options can also be embedded within the file being
plotted. Any line which starts with an opening square bracket ([) will cause BAR to
parse the string within the brackets as if it were typed on the command line after
all the other arguments.

Any line starting with a double-quote (") is ignored, so can be used as a comment
line.

Any line which starts with characters enclosed in round brackets () will use those
characters as a label for that entry. The data within round brackets will otherwise
be ignored.

Utilities

[BAR]

BAM

All remaining tokens on a line are treated as files to be plotted.

The simplest form of a data file is simply a list of numbers, in one or more
columns, such as shown below:

56.1

26.1

43.1

22.2

45.7

18.2

39.4

16.7

35.5

16.3

30.9

14.1

28.6

10.0

29.2

11.0

34.3

10.1

37.3

15.5

45.7

20.3

50.0

24.4

The 3 fields of this file could be plotted as a STACKED BAR graph using the
command:

bar file,l file,2 file,3 +v +g "t=1987 Production" 1=H/W 2=S/W 3=Other

If this file is always plotted with the same arguments, you could choose to embed
the parameters within the file, by putting the following lines at the beginning of the

" field 1 is plotted first

[f=2]

[f=3]

[+v]

[+g]

[t=1987 Production]

[1=H/W]

[2=S/W]

[3=Other]

With these extra lines, the same plot will result from the command:
bar file

In order to demonstrate the capabilities of BAR, the above data was used to
generate the following actual untouched graphs:

[BAR]

Utilities

bar file,l file,2 file,3 +g "t=1987 Production" 1=H/W 2=S/W 3=Other

Utilities

BAM

STACKED,BAR GRAPH

bar fiie»lfile»2 fiie,3 : +g +v "t=1987 Production 11 1=H/W 2=S/W 3=Other

[BAR]

Utilities

BAR

LINE GRAPH

bar file,l file,2 file,3 +g +1 "t=1987 Production" 1=H/W 2=S/W 3=Other

See Also:

DUMP_IBM

MOUNT

Utilities

[BAR]

BEEP - Beep a user on another terminal/machine

Syntax:

beep userid [ message ]
beep [node] tty [message]

userid - A user signed on in the system.

node - A node within a QNX network.

tty - The tty number to beep.

message - Message to send.

beep gord

beep gord Its time for lunch

beep 3 Please get off the modem port

beep 1 3 Please get off the modem port on node 1

Description:

BEEP will send a message to a user. The user may be logged in on the console or
any terminal in the network. A stand-alone system is considered as a single node
network. If the message is omitted, the user will only receive a series of beeps to
attract attention. The user might then drop into CHAT or MAIL. If a message is
specified, it will be printed at the current cursor position on the user’s screen. This
may cause minor confusion if the user was running a full screen application like
ED. The beeps will be sent right after the message is displayed.

Note that BEEP opens the user’s screen for write. If the user has partially typed in
a line, then BEEP will wait for a carriage return. If a user is signed on more than
once, the message will be delivered to each screen the user is logged onto.

See Also:

APB

WHO

[BEEP]

Utilities

BOOT - Select an OS file for disk booting

Syntax:

boot osjilejiame [options]*

Options:

-pause

4-qnxloader
-qnxloader
c=config Jile
d -disk_driver

ROM Boot options:

+Hard_disk - Hie disk is going to be a hard disk device.

+F loppy disk - Hie disk is going to be a floppy disk device.

■Partition - Is a partitioned disk and the boot loader will

be made aware of this.

-Partition - Is not a partitioned disk and the boot loader will
be made aware of this.

Examples:

boot 1 :/netboot/os.2. lOatp

boot 3:/netboot/os.2. lOatp d=/drivers/disk.at +q

boot 3:/netboot/os.2.10atp

Description:

BOOT selects the name of a file you wish to boot from disk. The disk may be a
floppy' or a hard disk.

To understand the purpose of title +qnxloader, some background information on
hard disk booting is necessary.

Booting from hard disk is a two step procedure. The BIOS first reads in block one
of the hard disk and transfers to a bootstrap loader which decides which of the 4

partitions is active. This loader reads in the first block of the active partition and
transfers to another bootstrap loader. This loader is operating system specific, and
loads in the operating system for that partition.

Don t pause.

Write the special QNX loader.

Remove special QNX loader.

A configuration file to bind into the OS.
A hard disk driver to bind into the OS.

Utilities

[BOOT]

BOOT

Block 1
of disk

Partition 1

Partition 2

• • • •

+qnxload

OS 1

Os 2

level 1

level 2

loader

The first level bootstrap loader as provided by DOS will always boot the active
partition as set by the QNX or DOS FDISK program. If you specify the
+qnxloader option, we will replace this bootstrap with one that will still default to
the active partition, but will pause for several seconds and allow you to override
from the keyboard by typing a single digit from 1 to 4. This gives more
flexibility. If you have non-standard hardware, or are already using a special
loader, then this loader may cause you problems. For 99.9% of all installations we
recommend you use the QNX loader. You need only specify the +qnxloader op¬
tion once.

When you specify +q option, BOOT looks at the partition loader already on the
disk (probably DOS’s) and if it is different than the QNX loader, saves it away to a
file called / config/hdiskMr . Then, at any time in the future, if you use the new -q
option, you can restore the original loader back to the partition sector.

When QNX boots, it needs a hard disk driver in order to access the hard disk.
Unlike DOS it cannot use the BIOS driver which does not work in protected mode.
You must specify which hard disk driver to bind into a hard disk boot. This is
done using the d -disk_driver option. This option takes the name of a mountable
disk driver, and creates a file called /config/hdisk.cfg which will be loaded in from
hard disk along with the operating system file. You need only specify the d=driver
option the first time you configure for hard disk booting.

You may have several OS image files under the directory /netboot, and you may
use the BOOT command to select which one you wish to boot from. This is very
handy if you download a beta version of an OS from the QNX Update System and
wish to try it out.

boot /netboot/testos - Select a test version to boot

The BOOT command also allows you to specify a configuration file which lets you
change some of the operating system defaults; such as the number of open files
supported. This is specified as a c=filename option. You may select any file
name, however we recommend that you choose names like those shown below. If
you boot across a QNX network, then you must use a name as shown below.

[BOOT]

Utilities

/conflg/sys.cfg - Single machine.

/config/sySoCfgoiiii - Network machine*

The sys.cfg file is created and maintained by the OSCONFIG command, ft takes

the file name as an argument. For example

©sconftg 3 "/conflg/sys.cfg

would create a configuration file for a single non-networked machine. It does not
become active until you use the BOOT command to set it.

boot 3:/netboot/os.2.10pcat c=3s/config/sys.cfg

NOTE: Once booting from hard disk, you should not remove the O/S file, the
driver file or the config file.

Inethootlosname

/config/hdisk.cfg

/conflg/sys.cfg

You may copy a new file on top of them but NEVER remove them (FREE, RM,

...) and then create a new one, even if they have the same name. The BOOT
command saves away the absolute start blocks of each of these files, which will
change if the file is removed.

ROM BOOT options :

+Hard_disk

The boot disk is going to be a hard disk device. This option conditions the boot

loader so that it uses the hard disk BIOS read call instead of the floppy disk BIOS

read call (ie: register dl has 0x80 ’or’ed in for the read).

+Floppy

The boot disk is going to be a floppy device. This option conditions the boot loader
so that it uses the floppy BIOS read call instead of the hard disk lead call. (ie:

+PartItIon

The boot disk being prepared is a partitioned disk and the boot loader placed on the
disk will be made aware of this. Normally, floppy and ROM disks would not use
this option.

Utilities

[BOOT]

BOOT

-Partition

The boot disk being prepared is not a partitioned disk and the boot loader placed on
the disk will be made aware of this. Normally, floppy and ROM disks would use
this option.

These options should be used to descibe what the ultimate ROM disk will boot as,
and should not necessarily describe the media the boot command is executed on.
For example, if you had a ROM disk driver that acted like a hard disk, you would
use the +H option, even though you were preparing the ROM image on a floppy
disk.

See Also:

NETBOOT

MOUNT

OSCONFIG

[BOOT]

Utilities

BREAK - Break a task

Syntax;

break task-id

• This is a local shell command •

Description;

BREAK allows a task whose taskid is known to be killed gracefully. The taskid
can be found by using the TSK command. Only tasks which are created by
yourself can be broken. The super-user can break any task in the system with the
exception of the operating system and user administrator tasks.

BREAK is typically used for aborting background programs since they are no
longer associated with a terminal, and therefore cannot be terminated with the
BREAK key. A background LIST program is an example of a task which a user
may wish to break.

BREAK is the preferred method of killing tasks, since KILL will not allow a task
to terminate normally, so may result in devices or files being left in an
indeterminate state. BREAK will usually only kill a task which manages critical
resources at a time where it is safe to do so.

See Also:

PRTSC

Utilities

[CALC]

CAT - Concatenate input files into one larger file

Syntax:

cat [inputJile]* [>outputJile]

Examples:

cat smalll small2 >big

cat filel flle2 file3 file4 >massive

cat file

cat filel - file2 >new
cat >easy

Description:

CAT will concatenate a list of files creating one larger file. The default output is
the standard output (usually the terminal), which the user will typically redirect to
a file or line-printer.

The standard input (keyboard) can be specified with a dash (-) which will cause
CAT to insert data taken from the standard input until an end-of-file (Ctrl-d on
keyboard) is encountered (as shown in the example). Also, you can quickly
create a file without an editor by using CAT, as in the last example, which will
read data from standard input until end-of-file.

See Also:

SPLIT

[CAT]

Utilities

CC - Compile Command (C, Basic,...)

Syntax;

cc file [options]*

Options:

+Asm - Do not ran the asm command, and retain the
.a file (asm input).

-core - Do not ran the link command even if only one

source file is entered, and retain the .o file
(link input).

-Core - Same as -core.

-Exec - Don’t execute any commands (debug).

- Include any libraries needed for source modules
ending in the suffix c. (see +W c option)

-Nested - Nested comments will all terminate on first
^ Usually every nested level requires its own end sequence.

+Optimize- Run the "C" optimizer.

+optimize - Run the "C" optimizer.

-preproc - Do not ran the C preprocessor (CPP) (default).

4-preproc - Run the C preprocessor (CPP).

-i-Preproc - Only ran the C preprocessor leaving the output
in the same name with the suffix capitalized.

For example test.c -> test.C
test.b -> test.B

•fQbug - Create symbol tables for a symbolic debugger.

-Remove - Don’t remove the temporary files.

-Stackchk - Suppress the stack checking code produced by
the code generator, (same as +Wi,s=0)

-Tmp - Do not use /tmp as the work directory.

Temporary files will be created in your current
directory.

-Verbose - Suppress the printing of each phase of
compilation.

+Verbose - Very verbose output.

Utilities

+8087 - Force the code generator to produce native 8087

code for floating point operations. During link
the native 8087 system libraries will be
searched. The default is to generate software
interrupts into a floating point shared
library. Native code requires an 8087/80287
but can be as much as 500 times faster.

+W c 9 arg - This option is used to pass the argument
(arg) to a specific processor (c) as follows:

? cpp C pre-processor

a asm assembler

b cbl basic parser

c ccl € parser

I cc2 code generator

y yacc yacc

encore - Specify name of compiled loadfile.

E =obj.o - Use the indicated object module in place of
the system one in /lfb/entry.o.

0=objdir - Place all object modules in the indicated
directory rather than, the current directory.

. T =treesiz - The parsers and code generator build parse
trees in internal tables. Very complex
expression may require you to increase this
space. The default is 2500.

+386[/16] - Internal use only.

The following three arguments cause the optional €

preprocessor to be invoked (forcing +p)» and are used

as follows:

d e=name=value - Works as if "#define name value" was in
the source.

tin -name - Removes any "#define name " implemented by the

C preprocessor.

in =dir - Adds dir to the automatic library search
for #include <name.h> files.

Examples:

cc hanoi.c

Compile hanoi.c and create an executable program in the current directory

with the name hanoi.

[CC]

Utilities,

cc hanoi

One by one append the following suffixes to the file hanoi, {.c, .b, .y, i, .a}
and on a match invoke the appropriate parser. If the file hanoi.c exists, then
this will have the same effect as the previous example.

cc clock.c -S

Compile clock.c and create an executable program in the current directory
with the name clock. The program will not contain stack checking code. This
will make it slightly smaller and faster.

cc clock.c +Wc ? e=error§

Compile clock.c and create an executable program in the current directory
with the name clock. Any errors detected during compilation will be placed in
the file errors.

cc prtsc.c c=/cmds/prtsc +V

Compile prtsc.c and create an executable program in the /cmds directory with
the name prtsc.

cc banner.c -c de=fimction=l

Compile banner.c using the optional preprocessor to add ”#define function 1”
and retain the output banner.o in the current directory, (link was suppressed)

cc fastprog.a -c +Wa,+286

Assemble fastprog.a program and pass the argument +286 to the assembly.
The link was suppressed and an object module fastprog.o will be produced.

cc baslc.b csub.c

Compile basic.b and C function csub.c producing two object files (. 0 ). The
two object files will be linked and, because a basic program was compiled, the
basic run time library "/blib" will be included during the link. Since more than
one file was specified, the executable will be in a file called core.

cc basic.b csub.c c=basic.test

Same as above but executable (core) placed in basic.test.

cc *.c /mylib/fun.o +Lb

Compile all C programs in the current directory. Object modules (. 0 ) will be
produced for each C program. The object modules will be linked along with
/mylib/fun.o creating an executable load module called core. Search Basic
libraries.

cc *.0

Pass all object modules to the linker and produce an executable load module
called core. Don’t forget the +8087 option if you wish inline 8087 code. You
may also need to specify the +Lc option to search language dependant

Utilities

[CC]

libraries.

cc x=ofiles

Invoke the linker with the option x=ofiles.

Description:

CC is the QNX compiler interface. It takes a list of source and object modules on
the command line and invokes the appropriate parser to compile each file. Object
modules are passed straight through to the linker. The choice of parser to use is
based upon the file suffix.

x -> C compiler /emds/ccl

Jb -> Basic compiler /cmds/cbl

*a -> Assembler /cmds/asm

j -> Yacc /cmds/yacc

A -> Code generator /cmds/cc2

The parser must exist in order for you to use it. The CC command was designed to
work with potential future parsers and may contain entries for parsers which are
not yet available. If the suffix on a file is omitted, a scan for a file with each of the
possible suffixes is made. Upon a match the appropriate parser is invoked. The
suffixes are scanned in the following order.

x -> -> „y -> i ~> „a

If only one source file is given, the linker will create an executable program in the
current directory, with the same name as the input file, but with the suffix stripped
off. If more than one file is specified, the executable will be placed in the file core.
You may use the linker option c -name to force the destination of the executable.

The -core option will suppress the LINK phase. This is a heavily used option by
developers which have many separate source files which they update and modify
individually.

There are special system libraries for each parser which will automatically be
included in the link when a source module for that parser is encountered. If only
object modules are specified, then only the standard C libraries will be searched.
You can include libraries using the +Lc or l=library option which is passed to the
linker. ■

cc *.o 1=/Mib (or use +Lb option)

cc x=oflles I=/blib (or use +Lb option), '

[CC]

Utilities

The code generator is capable of generating either native 8087 code or calls into a
mounted shared library for floating point operations. The default is to emit calls to

the shared library. This allows a program to ran on a machine which does not
contain an 8087 co-processor. One of two shared libraries may be mounted.

mount lib /config/float.slib (no 8087)

mount lib /config/float8087.slib (8087)

The second shared library is an order of magnitude faster than the first. Note that
this approach allows you to distribute one program which can take advantage of
the 8087, if it exists, or use software emulation if it does not. For really time
critical operations, the overhead imposed by the shared library can be avoided
completely by specifying the +8087 option, which will cause the code generator to
produce native inline 8087 code. This switch will also link in the native 8087 math
libraries. No shared library need be mounted but an 8087 MUST be present.

The QNX C compiler contains a limited C preprocessor which should handle 98%
of all C programs. By building the preprocessor into the parser, it eliminates one
phase, resulting in a faster compilation. You may use the full implementation of
the C preprocessor by specifying the +p option. Very large programs may cause
the C parser (ccl) to ran out of memory due to a large number of #defines. Each
define takes up memory. In this case the preprocessor will strip the #defines,
giving the parser more memory to work with.

In some cases complex defines or macros may produce parser error messages
which are difficult to understand. By using the +P (capitalized) option, the
expanded output will be left in a file with the same name, but with the suffix
capitalized. You may examine this file with the editor.

The full implementation C preprocessor also implements a number of built-in

manifests including: i8086, qnx, quantum, DATE , FILE , and LINE .

_DATE is a string containing die date the file was compiled. FILE and

_LINE_are dynamic manifests containing the filename and linenumber of the

source.

You may occasionally wish to examine the assembly code produced by the code
generator, maybe in attempt at optimization or perhaps in tracking down a
suspected code generator bug. The +Asm option will stop the compile after cc2,
leaving a file with the suffix .a.

The -Stackcheck option will suppress the generation of stack overflow code by
cc2. This typically results in slightly smaller and faster code. We recommend that
you leave stack checking on for files that contain recursive functions.

Utilities

[CC]

All arguments and options that are not listed above are assumed to be instructions
for the linker and will be passed to the LINK command. Object modules (files
ending in .o) are also passed directly through to the linker. The choice of upper
case options is deliberate to avoid confusion with options known by the processors
(parser, code generator, assembler and particularly the linker) invoked by CC. For
example, you can change the default stack size by specifying s =stacksize which
will be passed to the linker. The default of 2000 bytes may need to be increased for
recursive programs or programs which place large arrays on the stack. If possible
move arrays outside of functions to avoid having to override the stack size.

If you need to specify a parameter to any of the processors, you may use the
+Wc,option. Check die documentation on each processor to determine its options
or type its name followed by a question mark (?).

ccl ?

The following charts illustrates the flow of control for the different parsers
invoked.

WITHOUT THE PRE-PROCESSOR

.y .c .i .a .©

yacc ' ccl■ 1 cc2 1 asm ' link

.b . i A A A

- obi - 1 I I

WITH THE PRE-PROCESSOR

•y .c .C .± .a .o

yacc - cpp “ ccl - cc2 .-- asm - link

.b ,B .i A A A

cpp cbl - 1 I I

• a

[CC]

Utilities

See Also:

PWD

Utilities

[CD]

CHATTR

CHATTR - Change Attributes of a file

Syntax:

Change attributes of file.

Change attributes of directory.

Change the group number of a file.

Change the group member number of a file.
Change name of file.

Change file permissions (for my group).
Change directory permissions.

Change file permissions (for other users).
Change directory permissions.

Same as combined po= and pg= (files).

Same as combined po= and pg= (directories).
Change file status.

Change date to current date.

Make un-busy (Caution: see text).

chattr filename* options*

a=[+l»][rwaem] -

a=[+l-][rcbm]

g=group
m= member
m-name

pg=[+l-][rwaem] -
pg=[+l-][rcbm] -
po=[+|-][rwaem] -

po=[+H[rcbm] -

P=[+l-][rwaem] -

P=[+i-][rcbm]

s=[+l-][bmu]

+date

-busy

chattr old n=new
chattr main.c g=12 m=4
chattr core p=-wa a=+e

chattr /user/bill +d
chattr file.dat s=-b

- Change name of "old" to "new"

- Change ownership of file.

- Remove write and append permis¬
sion from "core", add execute
attribute.

- Update date of file to today

- Unbusy a file (Caution: see text).

CHATTR allows the status, attributes, permissions, date, owner,
to be changed.

The status flags which can be changed on a file are

and name of a file

b - BUSY. Set when the file is opened for write. If the system crashes

[CHATTR]

Utilities

CHATTR

without closing the file, this bit will be left set in the directory entry,
m- MODIFIED. Set whenever a file is modified (open for W, R/W or A)
and cleared by the BACKUP command,
u - USED. This flag can only be cleared. It is the equivalent of zapping the
file with the ZAP command.

The attributes and permissions which apply to files are:

r - READ. This capability allows files to be read or copied,
w - WRITE. This capability allows data to be written into a file. Old file
contents will be lost.

a - APPEND. This capability allows new data to be written at the end of a

file. The current contents of the file are not changed.

. e - EXECUTE. This capability allows a file to be executed. All files created

by the linker are created with execute permission. Any copies of an
executable file will also need this permission before the file can be
executed.

m- MODIFY. This capability allows the CHATTR command to change die

attributes, permissions, name, owner, and date of a file. If this option is
ever turned off, the attributes can never again be changed. Modify permis¬
sion can only be turned off by specifying a=-m. Take care never to
remove modify permission from a file which doesn’t have write permis¬
sion, or it will remain forever!

The attributes and permissions which apply to directories are:

r - READ. This capability allows directories to be read or listed,
c - CREATE. Allow new files to be created under this directory,
b - BLOCK. Prevent directory searches below this directory,
m- MODIFY. Same as for files.

Attributes of a file or directory apply to the owner of the file and the super-user
(group 255). Permissions are those attributes which are permitted for other users.
There are two types of permissions

Group - these apply to members of the same group
Other - these apply to members of other groups

Careful setting of permissions on directories and files allows a user to "protect" his
files from other users of the system in a multi-user environment.

The owner of a file can be changed with the g- and m= options. These options will
usually be used by the operator when creating initial user directories. The group
and member number must be a number from 0 to 255. The owner (group.member)
number is assigned to a user in the password file. Only the super-user can invoke

Utilities

[CHATTR]

CHATTR

the g= option. The nt= may be used by the super-user (group 255) or a group
leader (member 255 of a group).

Filenames can be changed using the n= option. New names refer only to the lowest
level of the complete pathname. For example, to change the name of die file
"/user/joe/dirl/biU" (which has the name "bill"), one would use:

chattr /user/joe/dir 1/bill n=fred

Valid filenames contain 1 to 16 characters, consisting of upper or lower case letters

(they are distinguishable), numbers, underscores (_), dots (.), and dollar signs ($),
provided that $ is not the first character.

The date and time of a file can be updated using the +d option, which changes the
date and time stamp of the file to the current date and time. This is especially use¬
ful for upgrading files which were created or changed during a session where the
user neglected to set the system date.

Busy files can be made unbusy with the -b option. The command CHKFSYS
should then be run to verify that the unbusied file is consistent. If not, the file

should be copied to another file and the original zapped using "chattr s=-u" or
ZAP. An inconsistent file should NEVER be left on a disk and should NEVER be

released by using FREL.

See Also:

CHKFSYS

ZAP

[CHATTR]

Utilities

CHGRP - Change group (group number) of a file

Syntax:

chgrp group jiumber file *

Examples:

chgrp 4 fiiel file2

Description:

CHGRP changes the group number of the specified files to group jiumber. This
number must lie between 0 and 255 inclusive. Group 255 is a the super group.

Note that this is a shell file which invokes the CHATTR command.

See Also:

CHATTR

CHOWN

Utilities

[CHGRP]

CHKFSYS - Check entire file system for consistency

Syntax:

chkfsys drive [options]*

Options:

drive

b=file -
f-lpath -
-stats

+rebuild -

-fix

-pause

-verbose -

Disk drive on which to check file system.

File of bad blocks.( see DCHECK utility )
Check the indicated pathname only.

Suppress statistics calculation and display.
Suppress error messages relating to the bitmap.
Don’t fix anything.

Don’t ask user if errors should be fixed.

Don’t print names of files being checked.

chkfsys 2
chkfsys 2 +r

Check file system on drive 2.

Check file system on drive 2 in order
to rebuild the bitmap.

CHKFSYS will perform a consistency check of the file system on the requested
drive. It will recursively walk the file structure visiting every file on the disk.
During the walk checks are made on the directory entry of each file and the extents
that make up the file. A bitmap is constructed in memory which is consistent with
the block allocation of all files and directories on the disk. This bitmap is then
compared to the one on the disk. If they differ the user is given the option of
replacing the bitmap on disk with the one constructed in memory.

IMPORTANT: CHKFSYS should only be used when the system is idle. There
should be NO open files when CHKFSYS is running.

CHKFSYS is usually used to recover blocks which were lost through the use of the
ZAP and CHATTR command.

zap file

chattr s=-u file

Utilities

[CHKFSYS]

CHKFSYS

In this case CHKFSYS will complain that there are blocks used In the bitmap
which are In fact NOT used by any file. These blocks may be recovered by writing
the reconstructed bitmap back to disk. CHKFSYS will attempt to read each of

these blocks and will NOT mark bad blocks as available.

The b= option may be used to inform CHKFSYS of known bad (or marginal)
blocks. Each line of the file should contain 1 hexadecimal block number. The
block numbers must be sorted in ascending order.

If b= is not specified, then CHKFSYS will use the file "/bad_blks , if it exists on
the drive being checked. This file is created automatically by the command:

dcheck +mark

CHKFSYS will tell you if any files are using blocks which are now known to be
bad.

If CHKFSYS complains that a block is used by more than one file, it could ^
indicate one of two problems. If the b= option was specified, or 7bad_biks”
exists, then it probably indicates that the file uses a block which is bad and marked
as used in the bitmap. If there are no known bad blocks, then a multiple allocation
of a single block has occurred. In either case, the file should be saved on
ANOTHER disk (if possible) and then zapped. CHKFSYS should then be ran
again to update the bitmap, after which the saved file may copied back onto the
disk.

In general, whenever the bitmap is replaced, CHKFSYS should be run a second
time to ensure that the file system is indeed consistent.

CHKFSYS may also be ran after a system crash or power failure which has left
some files busy. The files may be made unbusy using the chattr command

chattr s=-b file

which may then be followed by a CHKFSYS to ensure that no damage to the file
system has occurred. QNX should be relatively immune to this type of damage. If
CHKFSYS complains, you may copy the unbusied files to another disk, zap them,
run CHKFSYS to recover lost blocks, then restore files. For example.

copy 2;/filel l:/f!lel

■ zap 2:/ft!el
chkfsys 2

Utilities

[CHKFSYS]

CHKFSYS

copy l:/fflel 2:/fiIel

If you are crashing the system often while debugging a program, you may wish to
always save, zap and restore files and only run CHKFSYS occasionally to recover
bad blocks. If you are sure that no disk I/O was in progress, it is probably not even
necessary to zap the files.

If the f= option is specified, then only the indicated pathname will be checked.

The pathname must start with a slash. This is not a complete check in that it
cannot check for multiple allocations of the same block to more than one file. For
example:

chkfsys 1 f=/user/gord/data
will check the file l:/user/gord/data.

In the event of the complete loss of a file system due to the destruction of the root
directory and the bitmap (first few blocks of the disk) you should refer to the
technical note on file recovery in your QNX manual.

See Also:

DCHECK

ZAP

QUANTUM TECHNICAL NOTE ON FILE RECOVERY

[CHKFSYS]

Utilities

CHKFSYS

copy l:/fllel 2:/filel

If the f= option is specified, then only the indicated pathname will be checked.

The pathname must start with a slash. This is not a complete check in that it
cannot check for multiple allocations of the same block to more than one file. For
example:

chkfsys 1 f=/user/gord/data
will check the file 1 :/user/gord/data.

In the event of the complete loss of a file system due to the destmction of the root
directory and the bitmap (first few blocks of the disk) you should refer to the
technical note on file recovery in your QNX manual.

DCHECK

ZAP

QUANTUM TECHNICAL NOTE 01 FILE RECOVERY

Utilities

[CHKFSYS]

In this case CHKFSYS will complain that there are blocks used in the bitmap
which are in fact NOT used by any file. These blocks may be recovered by writing
the reconstructed bitmap back to disk. CHKFSYS will attempt to read each of
these blocks and will NOT mark bad blocks as available.

The b= option may be used to inform CHKFSYS of known bad (or marginal)
blocks. Each line of the file should contain 1 hexadecimal block number. The
block numbers must be sorted in ascending order.

If b= is not specified, then CHKFSYS will use the file "/bad_blks", if it exists on
the drive being checked. This file is created automatically by the command:

dctieck +mark

CHKFSYS will tell you if any files are using blocks which are now known to be
bad.

If CHKFSYS complains that a block is used by more than one file, it could
indicate one of two problems. If the b= option was specified, or "/badjblks"
exists, then it probably indicates that the file uses a block which is bad and marked
as used in the bitmap. If there are no known bad blocks, then a multiple allocation
of a single block has occurred. In either case, the file should be saved on
ANOTHER disk (if possible) and then zapped. CHKFSYS should then be run
again to update the bitmap, after which the saved file may copied back onto the
disk.

In general, whenever the bitmap is replaced, CHKFSYS should be mn a second
time to ensure that the file system is indeed consistent.

CHKFSYS may also be run after a system crash or power failure which has left
some files busy. The files may be made unbusy using the chattr command

chattr s=-b file

copy 2:/filel l:/filel

zap 2:/filel

ctikfsys 2

[CHKFSYS]

Utilities

■SHi

CHMOD - Change mode of a file

Description;

Please refer to the documentation on the CHATTR command.

See Also:

CHATTR

CHGRP

CHOWN

Utilities

[CHMOD]

CHOWN - Change owner (member number) of a file

Syntax:

chown member jiumber file *

CHOWN changes the member number of the specified files to member jiumber.
This number must lie between 0 and 255 inclusive. Member 255 is a group leader.

Note that this is a shell file which invokes the CHATTR command.

See Also:

CHATTR

CHGRP

[CHOWN]

Utilities

CLOCK - Display Time and Date On Console

Syntax;

dock [options]*

Options;

-date - Suppress display of the date.

-hour - Suppress display of the hour.

-seconds - Suppress display of the seconds.

-ampm - Suppress display of the AM or PM.

-key - Suppress display of keyboard shift status(s).
a -attr - Select display attributes (hex).

j(g>«r« o

clock a=H04 & (white on blue, then inverse)

Description:

This command will maintain a real time display of the date and time in the top
right hand comer of your console display. It will also display the current shift state
of the CAPS LOCK key, NUM LOCK key and the ALT key. This command
automatically adjusts its priority to level 15 so that it does not compete with other
tasks.

The display attribute bits are defined as follows:

|eBBBxFFF|xxxxuihb|

b - enable blink

h - enable highlight

i - enable inverse

u - enable underline

FFF - foreground colour (if enabled)

BBB - background colour (if enabled)
e - enable colour

x - don’t care

Utilities

[CLOCK]

CLOCK

This command is included in your "/config/sys.init" file. Should you wish to
remove the feature, you may edit "/config/sys.init" removing the invocation. The
command may also be killed at any time by typing the command "slay clock".

Users with battery backup-up clock/calendar hardware may wish to use the RTC
command to set the date. This command would be placed in your "/config/sys.init"

file.

See Also:

DATE

RTC

[CLOCK]

Utilities

CLRHOUSE - A distributed database and name server

Syntax:

clrhouse start [-poll] [p ~poll_sec] &.
clrhouse poll [n-node] [+me]
clrhouse locate [n=node]
clrhouse stop n -node

Examples:

clrhouse start &
clrhouse locate n=l
clrhouse stop n=4

Description:

CLRHOUSE maintains a distributed database for the naming of tasks. Like the
TIMER task it may be required for some applications. Developers should read the
technical note mentioned in the SEE ALSO section below.

STAET

You may ran CLRHOUSE on up to 3 nodes in the network. Upon starting, each

task will immediately poll each node in the network for iris list of attached names.
It will then go into a slow poll mode to refresh this information. This slow poll
period may be changed using the p -poll_sec options. It defaults to 10 seconds.
You can suppress slow polling completely by specifying the -poll option. The
slow polling is not the major means by which the clearinghouse keeps informed of
task names in the network. Each time a name is attached or detached, the
clearinghouses are immediately informed. The slow poll is a safety net to handle
extraordinary error conditions which might cause it to miss an attach or detach
request from a task.

POLL

You can force all the clearinghouses to refresh their infomiation on a node by
using the POLL option. If you specify a node using the m-node option then the
clearinghouses will immediately poll that node for it’s list of names. The option
+me can be used as a short form for n-myjiode. If you do not specify a node then
all nodes in the network will be quickly polled. This can be used to quickly update
the clearinghouses after a severe network disturbance (for example, a
clearinghouse node was disconnected from the network) where you believe their

Utilities

[CLRHOUSE]

CLRHOUSE

data is not current. It is doubtful that this option will be needed unless you elect
not to slow poll.

STOP

You may kill the clearinghouse by using the SLAY command or the STOP option
to CLRHOUSE. If you use the stop option you will have to identify which

clearinghouse to stop using the n=node option. The command

tsk info

will list the nodes which are running a clearinghouse.

LOCATE

When a node boots over the network it inherits the list of nodes which are running
a clearinghouse. If you boot from disk you will not know this information. If the
clearinghouses are slow polling you can wait until you are polled (thus learning
each clearinghouse one by one) or you can execute the CLRHOUSE command
with the LOCATE option. This will poll each node requesting it’s list of
clearinghouse nodes. The first node to satisfy the request will stop the poll and
update your list. In a stable network this will typically be the first node polled.
You can force the poll of a specific node only by specifying the m=node option.

This command would typically be placed in the sys.mit.wn file of a node booting
from disk.

See Also:

NAME functions in the C compiler binder.

Technical note on "Attaching and Locating Task Names"

[CLRHOUSE]

Utilities

COMM - Modem communication handler

Syntax:

comm [options]*

Options:

2i-modem_answer_string-

b =baud

B =default_baud

c=login command
&=startjieiay

f=mail_command

\-modemJnit_string
1 -log _path
m-greetingjnessage
greeting Jile
n=net_address
p=pickup_on_ring

q=quietjime_limit
r=modem_ok_response -
s=bbsjcommand
%-modemjimeout

-autopar

+ATI_2400etc

-CTS_check

-dropline

+debug

+hayes

+locked_baudrate

+pass_exception

-prompt

-recycle ' -

Command to force modem to answer.

Specify a baud rate to try. Multiple
fo= options can be given from lowest to
highest. Default is: b=300 b=1200 b=2400.
Default baud rate to select when the modem
responds with "CONNECT" and not a bapd rate.
By default this is 300.

Command to execute for normal login.

Delay in seconds after die connect before
starting the selected login program. The default
is 2 seconds.

Command to execute for mail transfer.
Initialization string for modem.

Name of directory for log files.

Initial greeting message to display.

Initial greeting file to display.

Mail network address to display on connect.
Number of rings required for answer. This
can only be used with the a= option.

Number of minutes without input before hangup.
Modem response for command acceptance.
Command to execute for bulletin board system.
Modem timeout for response (in 50 msec tics ).
Supress automatic parity.

Condition COMM to support this modem.
Supress checking for CTS modem status.

Supress dropline function.

Enable output of debug messages to log file.
Hayes compatible modem.

Force locked baudrate to the modem.

Enable passing of hangup exception.

Supress "Please type .... " message.

Supress modem re-initialization after 10 minutes
of inactivity.

Utilities

[COMM]

COMM

-i-verbose - Enable more detailed log messages.

Examples:

ontty 3 comm b=1200 +h i=ATS0=0| a=ATA|

ontty 3 comm c=zarcon b=2400 +h i=ATI| "m=Welcome to zarcon2"
ontty 3 comm b=300 b=1200 b=2400

Description:

The purpose of COMM is to make a QNX system or network accessible by phone
with a modem. The reason for a special utility is that, unlike a serial link to a
terminal where the link settings are known, modems tend to operate with variable
link settings. COMM is able to communicate with the modem to determine these
settings and to detect when the modem hangs up the phone line so it can remove
any tasks created during the call. COMM performs the following functions:

1. Baud rate detection and selection.

- 300,1200, 2400, etc.

2. Parity and bits / character detection and selection.

- even, odd, mark, space, none, 7 bit, 8 bit.

3. Initial welcome messages, a welcome line and/or a welcome screen.

4. The command to execute after baud and parity determination (eg: LOGIN).

5. Removal (killing) of all created tasks upon loss of carrier (hangup).

If possible, your modem should be configured to provide the CD (carrier detect)

RS232 signal to the computer so that COMM will be able to detect the modem
status ( on or off line ). Likewise, the DTR ( data terminal ready ) RS232 signal
should be connected from the computer to the modem, so that COMM and other
programs can force a hangup if necessary. Your modem should be programmed to
force a hangup and reset itself when the computer ’’drops” DTR. For a Hayes
modem, this command is typically "AT&D2”, but check the manual for your
modem since this command may vary.

After COMM has answered the phone and determined the baud rate, COMM will
wait for the delay specified with the &=start_delay option (default of 2 seconds).

This delay exists to avoid the burst of noise characters that often occur when two
modems first connect. After the delay, if a single line message was specified with
the m ^greeting jnessage option, it will be displayed. COMM will then perform
various checks depending upon which command line options were specified. If a
mail handler was specified with the f =mail_command option, COMM will look for
the protocol characters that indicate an incoming mail packet is arriving and start

[COMM]

Utilities

COMM

the specified mail handler. Similarity, if a BBS ( Bulletin Board System ) program
was named with the $=bbs_command options, a request for the activation of the
BBS program will be checked for. Note that any commands specified must have
full paths, for example, the LOGIN default command is "/cmds/Login".

The input sequences COMM checks for are:

..<Enter> - Execute the LOGIN, or t=command command.
<Escape> - Execute the BBS specified with s -bbs_command.
Mail Protocol - The f -mail command mail handler will be started.

If COMM determines that a human caller is present, the file specified with the
M-greeting Jile option will be displayed, after which either the LOGIN,
c -command or BBS system will be started. If no special commands have been
specified, LOGIN or the command specified with the c-command option will be
started as a son task, without any delayed checking for alternatives.

If the user doesn’t enter any characters for five seconds, COMM will default to
either the BBS program (if specified), or a command (specified with the
t-command option ), or LOGIN.

As part of the baud rate determination, COMM will post an environment variable
called BAUD which is set equal to the baud rate for the modem connection. This
variable is useful because many high speed modems operate with the serial link
between the modem and the computer at a fixed, high speed (usually 9600 or
19200 baud ) and then use hardware flow control to regulate the flow of data for
slower connections. Since the true baud rate cannot be determined by the stty
setting, COMM must post this information as an environment variable so that the
tasks started by the dial-up user can determine the true transfer rate. As an
example, QCP file transfers with fast modems benefit from having a packet size of
16K, rather than 2K. If the program detects that a high baud rate is in effect, it can
set the "s=16000" option on QCP to provide faster file transfers.

In addition to setting the baud rate in an environment variable, COMM can also
keep a log of modem events. The 1 =log_path option can specify either a device
where modem logs are to go or the name of a directory where log files are to be
kept. If log_path contains a ’$’ character, it is assumed to be a device and data is
written directly to that device. If the ’$’ character does not appear in log_path, it is
assumed to be a directory path, in which case a 7’ and a file name of the form:

881118 <-» Year, Month and Day

Utilities

[COMM]

COMM

is appended to create a filename for the day's log. A directory of the name
"/commlog" is a good choice, since the COMM_REPORT utility will use this
directory by default. Note that the logging directory must be created before
COMM is started. The data written to the log file or device contains various
messages. For example:

7:53:55 am [l]$tty22, Connect 2400/MNP

7:54:00 am [l]$tty22, Executing: Vcmds/login 9 (Login)

8:04:55 am [l]$ttyl9, Length: 17:47 (Caller Hung Up)

8:07:43 am [I]$fctyl9, Connect 1200/Noee

8:07:46 am [l]$ttyl9, Executing: Vcmds/login 9 (Login)

8:21:16 am [l]$tty22, Length: 27:21 (Call Done)

8:21:52 am [l]$ttyl9, Length: 14:08 (Call Done)

8:21:58 am [l]$tty22, Connect 14500/PEP

8:22:00 am [l]$tty22, Executing: ’/cmds/login’ (Login)

The LOCATE and WC commands can be used to extract various facts from these
logs. For example, the command:

locate 2400 /commlog/881118 ] wc

could be used to determine the number of 2400 baud calls for that day.

When the user has finished his call and exited from the program he was running (
with LOGOFF, D or a hangup), COMM wil remove the tree of tasks created by

the user. If desired, COMM can be started with the +pass_exception option so that
hangup exceptions, rather than kill exceptions, are passed to the user’s tasks on
hangup.

For an organized shutdown of COMM, the command:
slay comm u=4000

will cause COMM to wait for the current dial-up session to complete before
terminating itself. This organized shutdown has some very important uses. If a
dial-up system must be taken down for maintenance, instead of waiting for a
chance when all the dial-up lines are inactive, or forcibly "evicting” people from
the system, setting the "shutdown" exception will cause COMM to terminate itself
on each line as the user on that line hangs up. Ultimately, there will be no COMM
sessions running and the system will be idle. A shell script which uses the

slay comm +t

[COMM]

Utilities

COMM

option can loop with a timeout until all the active sessions are done before starting
a backup or other maintenance oriented function. When the backup is done, the
COMM sessions can be restarted. If COMM is being used with the
a -modem jmswer_string option, the modems will not answer incoming calls while
COMM is not present.

While COMM is operating, it makes itself an administrator task so that it cannot be
accidentally "killed". If necessary, the SLAY command can be used to forcibly kill
COMM. Note that any applications the dial-up user is running will also be killed. -

slay comm u=8000 •

The q -quiet jime option can be used to limit how long COMM will tolerate a user
on-line without any input. Assuming q=i5 was specified, after detecting 15
minutes without user input, COMM would beep the user and display the message:

Please respond!

it anotner minute passed witaout user input, COMM would drop DTR, causing the

modem to hangup and terminate the user session.

COMM can operate in one of two modes. The first mode is designed explicitly to
work with Hayes compatible modems and the second is designed to work with
non-intelligent modems that do not provide connect messages. If your modem is
Hayes compatible, we recommend using COMM in the Hayes compatible mode.

Haves Mode

The +hayes option configures COMM to understand the messages output by a
Hayes compatible modem. COMM can be configured to initially program the
Hayes modem to answer incoming calls and then wait for the CONNECT message
to determine the incoming baud rate.

You can change the modem initialization string user by COMM with the the i=
option. The default string is "ATI", but a suggested string could be:

Utilities

[COMM]

COMM

ATS0=1 El QO ¥1 XI &C1&02

L Return to and mode after loss of DTR.
L BCD indicates carrier detected,

L Extended status set,

L English result codes,

L Result codes sent.

L Command char echo enabled.

L Answer after 1 ring.

With a 2400 baud (or better) modem, these settings can usually be programmed
into the non-volatile RAM in the modem with the "AT&W" command. If so, you
■ can set the modem initialization string to "ATZI", causing the modem to program
itself to the internally saved state. Also, the modem can usually be programmed to
reset itself to the internally saved settings on loss of carrier, or hangup forced by
DTR driven low by the computer.

The modem initialization string supports a number of special characters that are
processed by COMM rather than being passed to the modem. These characters,
and their actions, are:

| - Carriage return

- Ignored, usually part of a phone number
~ -1 second delay

A - Raise DTR

v - Drop DTR (forces a modem hangup and reset)
’ -100 millisecond delay

As the modem initialization string is processed, any characters not in this special
set are passed through to the modem, unmodified. Using these special characters,
modem initialization strings that perform many steps can be easily constructed. For
example:

¥ ^^a^^ATS0=1|

would force a hangup of the modem with DTR ( with 3 second delays around each
change of DTR ) and then program it to answer after the first ring.

To accept incoming calls your modem need not necessarily be programmed for
auto-answer. Another alternative is to provide COMM with an answer string. If the
answer string is provided, the modem can be set to not auto answer ( ATS0=0).
What will happen is that the modem will emit "RING" statements when an
incoming call is detected and COMM will detect the "RING" and provide the
answer string (typically "ATAI" ) to force the modem to answer. This has the
added advantage that your system will not answer the phone unless it is powered

[COMM]

Utilities

COMM

up and the COMM task is ready for the incoming call. We recommend operating
your modem in this mode.

If your modem answers with other than "OK ,! to commands, COMM can adapt to
this with the r-modemykjr espouse command line option.

We also recommend you default your serial ports to 8 bits, no-parity and one stop
bit for communication with other QNX systems.

The following are some typical invocations of COMM for a Hayes modem.

©ntty $mdm comm +h b=2400

oetty 19 comm M=/no!/msg +h +1 b=19200 i=ATS0=0| a=ATA| l=/comm!og

Non-Haves Mode

COMM can also handle non-intelligent, or non-Hayes mode, modems. When these
modems answer the phone, COMM will begin to receive the incoming data that the
remote user is typing. Starting at a previously specified baud rate (default of 2400
), COMM detects this incoming data and prints the message:

Please enter two periods (. 0 ) and press <Enfer>

If the baud rate is incorrect, any character typed by the user will generate a
communication error causing COMM to switch its baud rate and redisplay the
above message. The periods (..) and carriage return must be typed in order without
any mix of other characters. Every three characters entered will redisplay the
above message. Often, the sequence "ab.." seems to be most efective at generating
enough exceptions for COMM to be able to determine the line settings. Space
parity is treated as 8 bit, no parity by COMM.

After the caller has hung up, the baud rate is then switched back to the highest rate
and the process starts over, waiting for the next call.

If your non-hayes modem has a feature to print a string when a call arrives, you
should TRY to disable it since this may confuse COMM working in the non-hayes
mode. This is especially true if the string contains either a carriage return or a
period. You should also try to disable ECHO from the modem and any status
messages.

This is a typical invocation of COMM for a non-intelligent modem.

oetty 22 comm M=/nol/msg b=300 b=1200 b=2400 f=/commlog

Utilities

[COMM]

COMM

Recognizing the fact that COMM is a utility that many people would like to

modify for custom applications, the source for COMM is available on the QNX
Update System and is also shipped as a sample C program with the QNX C
compiler. There are also a number of technical notes downloadable from the
update system that detail how to configure various modems for use with QNX and

COMM.

See Also:

[COMM]

Utilities

COPY - Copy files

Syntax:

copy sourceJile destinationJile [options]*

copy file* directory [options]*

Options:

-date - Don’t copy the date.

+pause - Pause before copying (to change diskettes).

4verbose - Display filenames as they are being copied.

Examples:

copy *.c /cjsource - Copy all c files to the directory
/c_source.

cp testx $lpt - Copy file test.c to the line printer.

Description:

Copy is now identical in operation to the CP command. Please refer to the CP
utility for details on it’s operation.

See Also:

BACKUP

CHATTR

Utilities

[CP]

CRON - Schedule commands in background

Syntax:

cron [-Sogfile] [l=logfile] [t=tablefile] &+

Options:

-logfile - Do not append status information to
any log file.

1 =logflle - Use die indicated log file in place of

the default logfile /config/cronlog.

' t-tablefile - Use the indicated table file in place of
the default table file /config/crontab.

Examples:

timer &

cron -I t=/etc/crontab &+

Description:

The CRON command provides a convenient method for executing commands at
specific times without operator intervention. It requires that the timer administrator
be running in background.

Cron is a resident program that uses a list of times and program names contained in
the file /config/crontab. This file has a single line entry for each program to be
executed that contains the following six fields:

1. The minute in the hour (0-59).

2. The hour of the day (24 hour clock).

3. The day of the month (1-31).

4. The month of the year (142) OR

(a 3 letter monthname).

5. The day of the week (0-6 where 0 is Sunday) OR

(a 3 Setter day name).

6. A command to be executed in the background

Utilities

[CRON]

CRON

Any of the time fields may have:

a single value 3 exact

an upper and lower boundary 10-15 range

a series of values 2,5,11,33 list

a "*" to mean all values * all

Each element of a list may of course be a range. The following examples illustrate
some typical cron table lines. The indented comment text is NOT part of the cron
table file.

15 * * * 1-5 who »/etc/wholog

15 * * * mon-fri who »/etc/whoiog

At 15 minutes after the hour on Monday
thru Friday append the output of the who

command to the file /etc/wholog.

01*** /cmds/diskuse

At 1 AM each day run the shell command
file diskuse.

0 41,15 * * payrolljstartup

At 4 AM on the first and the fifteenth
run the program payroll_startup.

55 7 * * 1,2,3,4,5 ontty 3 comm

At 7:55 AM Monday thru Friday start the
dialup access routine. This assumes a reboot
every morning or multiple COMM programs will
start to stack up.

0 01 jan * mail s % users cnewyearmsg

On the first of january every year send mail
to everyone in the file users.

[CRON]

Utilities

CRON

The command which is scheduled to run will be run in background. Its standard
input will be the device $null and its standard output and error will point to the
console on which CRON was run in background.

Each time the cron table is read by CRON, or CRON schedules a program to run, a
status message is appended to the cron logfile unless the -logfile option was
specified. It is possible to run a command from CRON which prints then deletes
this file once a week.

If a time in the cron table has already passed when CRON is started, that command
will not be run. CRON reads the cron table file once (within 1 minute) when it is
started. If you modify the table file you may force CRON to reread this file by
setting a break exception on CRON. For example.

slay cron +break

Utilities

[CRON]

CRYPT

CRYPT - Encrypt/Decrypt files

Syntax:

crypt [ key] <inputjile >outputJile

Options:

key - Encryption key to use.

input Jile - Source file to encrypt.

output Jile - File to place encrypted output.

Examples:

crypt secret, ctable >table.x

ws "crypt qwerty <@ >@.x" p=*.c - Encrypt all C files

in current directory

Description:

CRYPT reads from the standard input and writes an encrypted version of the data

to the standard output. The KEY selects a particular transformation of the data. If
no key is specified, CRYPT will prompt for a key from the terminal (without
echoing it). CRYPT encrypts and decrypts with the same key. After executing
these two commands

crypt abc <filel >fi!e2

crypt abc <file2 >file3

file3 will be identical to filel.

CRYPT implements a one rotor machine with a 512 byte rotor. Such an encryp¬
tion scheme can be broken, however, the amount of work required is likely to be
large and not generally known.

Since the encryption relies heavily on the key, small keys (3 characters or so)
should be avoided.

CRYPT flushes all input to prevent users from recalling command lines in order to
redisplay the key.

[CRYPT]

Utilities

DATE - Display or set date and time

Syntax;

date [day [month [year [hour [min [sec]]]]]] [amlpm]

Options:

day - 1-32

month - 1-12 or jan-dec
year - 80-99 or 1980-99
hour - 1-12 or 0-23
min - 0-59

sec - 0-59

am - (used with 12 hour time)

pm - (used with 12 hour time)

Examples:

date

date 22 2 82

date 16 july 1982 4 30 pm

Description:

If no arguments are given, the DATE command allows the user to display the date
and time on his terminal. When changing the date, day is entered first followed
optionally by month and year. The current time can also be set by following the
date with the hour, minute, and second. 24 hour or 12 hour time (am or pm) can be
used. All arguments must be separated by spaces. Any missing arguments will
default to the current value.

For details of setting the QNX date from a battery backed-up clock/calendar, see
the RTC command.

See Also:

CLOCK RTC

Utilities

[DATE]

DCHECK - Check a disk for bad blocks

Syntax:

dcheck drive [options]*

Options:

b=num_hlks - Number of blocks (in decimal) to check
(default: all blocks).

4-mark - Mark bad blocks as used in the bitmap.

-verbose - Don’t display progress information.

4 -verbose - Display every bad block on the disk.

-pause - Don’t wait for a disk to be inserted.
f=first_blk - Start the check at this block number.

Examples:

dcheck 2 4-ra - Check all blocks on disk 2 and
mark bad blocks in the bitmap
dcheck 1 b=640 - Check first 640 blocks on disk 1
dcheck [3]1 - Check all blocks on disk 1 of node 3

Description:

DCHECK allows the user to verify that a disk has been formatted properly. The
utility will do this by attempting to read every block on the disk. Any blocks which
cannot be read will be displayed on the standard output (which may be redirected
to a file). Bad block numbers are displayed in hex. A summary of die number of
bad blocks will always be printed on the terminal.

If the number of blocks to check is not specified, then DCHECK will obtain the
correct number from the file system and check ALL blocks on that disk.

DCHECK can be used to check any formatted disk, including disks which contain
files. These files will not be damaged. If the disk has been initialized using
DINIT, the 4-mark option should be used to remove any bad blocks from the disk
allocation bitmap. This is especially tme for hard disks.

IMPORTANT: DCHECK with the the -f mark option should only be used when
the system is idle. There should be NO open files when DCHECK is running.

[DCHECK]

Utilities

©CHECK

When mark is specified, DCHECK will attempt to read the file /bad_Mks from
that disk. If found, DCHECK will read in the file which contains a list of all known

bad blocks, in sorted order. When DCHECK finishes, it will re-create the file
/bad_blks, after it has updated the bitmap. DCHECK will only add to this file,
allowing transient or marginal disk blocks to be detected, and avoided, by
repeatedly calling DCHECK:

dcheck 3 +mark
dcheck 3 +mark
etc.

The /bad_blks file is also recognized by the CHKFSYS utility.

DCHECK may be used to check a disk on another node. The disk may be
indicated explicitly via a [node] prefix or implicitly by specifying a remdisk which
you have mounted.

The file created by redirecting the output of DCHECK may be used as a data file
for the CHKFSYS command. This allows you to detect which file (if any)
contains bad blocks.

dcheck 3 >bad_b!ocks
chkfsys 3 b=bad_blocks

See Also:

CHKFSYS

DINIT

FDFORMAT

MOUNT

Utilities

[DCHECK]

OCOPY - Copy entire disk to a second disk

Syntax;

dcopy [source [destination]] [options]*

Options:

source
destination
+hard
-verify
k -size

b-nblocks
so -offset
d®=offset
-{-repeat
-pause

Source drive (default: 1).

Destination drive (default: 2).

Allow copying to a hard disk.

Don’t verify after copying.

Size of disk to copy in Kbytes
(default: ALL blocks).

Size of disk to copy in blocks.

Offset on source disk in diocks.

Offset on destination disk in blocks.
Continue copying until user types BREAK.
Don’t pause for non-floppy disks.

Examples:

dcopy 1 2 - Copy all of disk 1 to disk 2.

dcopy 1 1 - Copy a disk using a single drive.

dcopy -v +r - Make multiple copies of disk 1

without verifying.

dcopy 2 1 b=160 - Copy disk 2 to 1. Only copy

160Kbytes.

dcopy 3 1 so=640 k=320

- Copy the second 320Kbytes of
drive 3 to drive 1.

dcopy 1 3 b=640 do=640 +h

- Restore the second 320Kbytes
of drive 3 from drive 1.

dcopy [4]1 [6]1 - Copy disk 1 on node 4 to

disk 1 on node 6.

Description:

[DCOPY]

Utilities

DCOPY

DCOPY allows the user to make an exact copy of the diskette in the source drive'

(default 1) onto the diskette in the destination drive (default 2).

CAUTION: This utility is NOT meant for copying files. It is meant for copying
exact disk images. Use CP, or BACKUP for copying files.

DCHECK will prompt the user to load the diskettes into the appropriate drive and
type CR when ready. DCOPY will read as many blocks as it can from the source
drive into memory, then write them onto the second drive. This will be repeated
until the entire diskette has been copied.

Normally the data on the destination drive will be read back and compared with the
memory buffer to ensure that the data has been copied correctly. This can be
suppressed (to speed up disk copying) with the -v option.

The b= and k= options allows the user to make copies of only a portion of a disk.
The + r option allows multiple disk copies to be made without the need to key in
the DCOPY command every time. The so= option permits the first part of the
source disk to be ignored. Offset is specified in blocks. The do= option allows an
offset to be specified on the destination drive.

Note that a blank floppy diskette must be formatted before it can be copied to.

Although DCOPY is normally used to copy floppy diskettes, a ramdisk or a hard
disk can also be copied to/from floppies. TTie k=, so=, and do= options allow an
entire Hard disk to be copied onto several floppy diskettes. Command files
consisting of several DCOPY commands could be built to make this more
convenient. The -p option can be used to avoid the prompt message which results
when one of the disks is not a floppy.

For your protection, copying to a hard disk is not allowed unless you specify the
+hard option. This should protect against any typing errors.

You may DCOPY to disks on different machines. This may may be indicated
explicitly via a [node] prefix or implicitly by specifying a remdisk which you have
mounted.

See Also:

BACKUP

FDFORMAT

MOUNT

Utilities

[DCOPY]

DDUMP - Dump the contents of a disk block

Syntax:

ddump drive block [-verbose]

Options:

drive - Disk drive number (1..F).

block - Disk block number in hexadecimal (1..?).

-verbose - Don’t display as ASCII characters

Examples:

ddump 3 1 - Dump block 1 of disk 3

ddump 1 10A -v - Dump block 10A (hex) of disk 1
ddump [4]3 2 - Dump block 2 of disk 3 on node 4

Description:

DDUMP will display the contents of a disk block 16 hexadecimal bytes per line,
with the ASCII equivalent (if printable) displayed to the right of the line. If the
ASCII character is not printable, it is replaced with a dot (.).

The disk block is specified as a hexadecimal number.

Subsequent disk blocks can be displayed by typing CR for each new block. Any
other typed character will terminate DDUMP.

DDUMP may be used to dump a disk on another node. The disk may be indicated
explicitly via a [node] prefix or implicitly by specifying a remdisk which you have
mounted.

See Also:

MOUNT

NACC

[DDUMP]

Utilities

DEBUG - Invoke the system debugger

Syntax:

debug [command line ]

Examples:

debug - Drop into the debugger,

debug test argl >$Jpt - Debug the program ’’test"

Description:

If you wish to do source level debugging please refer to QDB in the C compiler
manual. This is a low level debugger suitable for debugging interrupt handlers.

DEBUG allows the system debugger to be used, provided that it has been first
mounted into the system. This should only be done once.

mount debug

The debugger is an absolute (hex) debugger which allows breakpoints to be set in

user programs, memory to be displayed and edited, code to be disassembled, and

I/O ports to be examined.

The debugger can only be invoked from the console. The debugger should never
be used in a multi-user environment. It disables interrupts and freezes the entire
system. It may be used to debug application programs as well as interrupt routines.

With no arguments, DEBUG will be entered with a 4K memory buffer at its
disposal. If a command line follows the keyword debug, then that command will
be loaded into memory before the debugger is called. In this case, the debugger
will have its default code and data segments initialized to those of the command
being debugged.

Breakpoints can be set on functions whose addresses have been determined from
the map which can be generated by the linker.

cc test m= 0 map.

cc x=ofi!e§ m= e map»

Utilities

[DEBUG]

DEBUG

Similarly, the addresses of memory variables can be determined from the linker
map and displayed in the debugger.

The debugger does not support line editing. If you make a typing mistake you may
cancel the entire line by typing a Ctrl c. When entering addresses, etc. all data is
assumed to be hexadecimal. Only the last 4 digits are valid (2 for byte data) so

typing mistakes can be corrected by i
last 4 digits are the ones you want.

type the

• mich that the.

Ib341d44 results in ld44

If you type a simple DEBUG, perhaps to examine an I/O port, you may return back
to the shell by typing the g command. If you debug a command, then your default
code (@ @) and data (@) segment will be set up to point to your program. Note
that the CS register displayed when you first enter debug will be pointing into the
shared library, NOT your program. All breakpoints will be placed in your real code
segment which the shared library will return to when you resume via the g
command.

A WORD OF WARNING. If your program allocates considerable memory via the
ALLOC, CALLOC, MALLOC or OPEN routines, then QNX may relocate your
data segment without updating the default data segment memorized by the
debugger when your program began execution. As a rule of thumb, the stack seg¬
ment (ss:) will be your real data segment which should agree with the value printed
for ds= when you type ?. If not, you may change your default data segment using
the @ command. Note that the default data segment is ONLY used for displaying,
examining and changing memory. Changing it does not affect the data segment of
your program. It is there to save you from having to type in a segment prefix.

When debugging multiple tasks, you may wish to change your default code and
data segment many times for convenience.

[DEBUG]

Utilities

DEBUG

Debug Command Summary

b address Set breakpoint at address

b seg'.address

b r Set breakpoint at return from C function

b Display breakpoints

c start finish destination Copy memory

c seg'.start finish segidest

d address Display memory. CR ends display

d seg'.address and SPACE displays another line

D address Disassemble memory

D seg'.address

e address Edit Memory

e seg'.address

EDIT commands

hex number
’c

SPACE

'.data

;data

Changes contents of memory

Changes to ascii character c

Leaves edit

Goes to next byte

Redisplays this byte

Displays previous address

Displays 8 bit 10 port

Displays 16 bit 10 port

Output to 8 bit 10 port

Output to 16 bit 10 port

Goes to short relative address

Goes to long (16 bit) relative address

Goes to the address found in memory

f seg'.startfinish data Fill memory with data

f start finish data

g address Go to address (begin execution)

g seg'.address

g Continue execution (or exit debug)

Utilities

[DEBUG]

DEBUG

1 start finish data
1 segistart finish data

r reg

rregdata

s count

t n

T n

u address

@ segment

@ @ segment

@ i mask

@ p

@ s data

Continue execution, but reset a breakpoint
at the same address

Locate data in a range. Up
to 8 bytes may be searched for.

Examine contents of register

reg : ax bx cx dx si di bp es ds cs ss

Change contents of register

Single step from last instruction. You may
type the space bar to step through your
code, one instruction at a time.

Execute count instructions or until
next breakpoint

Display last n C sfcackframes

Display last n instructions executed
while single stepping

Unbreak (remove break) at this address

Remove all breakpoints

Trap all Protected-mode interrupts.

Display registers

Define default data segment
used by d e f c commands

Define default code segment
used by D b u s g commands

Define interrupt mask which will be
restored when program resumes.

Change stack pointer

Change stack segment

[DEBUG]

Utilities

DEBUG

See Also:

LINK

MOUNT

QDB Symbolic Debugger

Utilities

[DEBUG]

- Define id of global name server

def server node taskjd [+local]

node - Node number where the server task resides.
taskjd - Task-id of the server task.

+local - Only change server on local node.

Examples:

def server 3 1 - make TASK_ADMIN on node 3 a

global name server.

The DEF_SERVER command defines the node and taskjd of a global name
server task. This may be a user defined task or a TASK ADMINISTRATOR on
any node. Global names are used by administrator tasks which provide network
wide services. The SPOOLER is an example of such a task. This command may
be executed on any machine and all machines in the network will be updated with
the information.

DEFJSERVER will attempt to update the global name server information on every
node in the network, unless the +locaI option is used. If it is, then only your node
will change its value for global name server.

This command is only useful with the networking version of QNX.

The default name server in a QNX network is task-id 0001 on node 1. Most users
will NOT need to change this.

See Also:

CLRHOUSE

SPOOL

TSK

[DEF_SERVER]

Utilities

DEFPIPE - Define temp files for pipes

Syntax:

defpipe path

• This is a local shell command ®

The DEFPIPE command allows you to change the pathname where temporary pipe
files are placed.

defpipe myjpipe

The default is

defpipe /tmp/..#n#$

Utilities

[DEFPIPE]

DIFF - Difference between two files

Syntax:

diff file! file2 [options]*

Options:

4-editor - Creates a script of line edit commands
which can convert file] into file2.

(see the LED command)

4-matching - Produces a script of matching lines in
the two files rather than the difference.

+raw - v^auscb ct ^nui ciCtCi oy unai duid

comparison of the two files. A file
match or mismatch statement will be
issued if necessary indicating the
characters (and character number) where
the mismatch occurred. The -v option
may not be used with 4-raw. This option
must be used when comparing binary files
such as commands.

-blanks ■ - Causes multiple blanks or white
characters to be ignored in line
comparisons.

-case - Causes case distinction to be ignored.

+heading - Displays the names of the files being

compared. This may be useful without any
other option or the +ra and +r options.

-null - Causes null lines to be ignored. This

option should not be used with the +e
or +r options.

[DIFF]

MFF

t-resync - Changes the minimum number of lines
required to match before the two files
resynchronize. The default is two, the
new value must between one and one
hundred.

s=mcix_diff - Changes the maximum number of lines
the files may differ by at any time before
being declared incomparable. The default
is one hundred.

t ^string - Define terminator string to print between

sections of text.

-verbose - Disables the "The two files compared
equal" message.

-write - Suppress "w" command in LED script
created by the +e option.

Examples:

diff versionl version2

- Creates a meaningful script of differences between the

files.

diff old new +e >chgs

- Compares the original file to the new version creating
changes which will convert the old file into the new
version. To recreate the new version use:

led old ccfags

diff Corel core2 +r

- Allows text or non-text files to be compared character by
character.

diff filel ftle2 +m

- Displays the similar text segments between the given

files.

Description:

Utilities

[DIFF]

DIFF

DIFF compares two files line by line searching for differences between them. It
can illustrate these differences by producing a meaningful script of edit-like
commands. The commands are of the form:

rangel C range2
[< fileljext]*

[> fileljext]*

Where:

rangel is line number range in file 1
range2 is line number range in file 2
C is the LED command append, delete or change
< indicates a line of text affected in filel
> indicates a line of text affected in file2

In many situations, several versions of a file may exist. You may reduce file space
requirements by saving diff files rather than multiple similar copies. When you
update a file, DIFF +e can summarize the session as a series of line editor
commands. Typically a file containing the LED commands will be much smaller
than the updated version of an original file. Thus, if several versions of a file are
necessary, a great deal of disk space can be saved by keeping one original file and
several difference files.

If similarities between the files are required, the +m option will display the files
corresponding line numbers followed by similar lines of text.

When it is necessary to compare files character by character (binary files), instead
of as lines of text, use the +r option. The output will state if the files are equal. If
not, the character position and corresponding characters will be given.

See Also:

LED

LOCATE

[DIFF]

Utilities

DINIT • Diskette Initialization

Syntax:

dinit drive [+hard] [k -size] [p=lprefix] [+suppress] [-pause]

Options:

+hard - Required if the disk is a hard disk,
k -size - Size of diskette in Kbytes,
p =lprefix - Name to give the root of the file system on that
disk (default is 7")

-pause - Don’t pause for diskette to be loaded.

+suppress - Suppress the writing of the root directory.

Examples:

dinit 3 +hard
dipit 1

dinit 1 p=/user
dinit 5 -p
dinit [3]1

Description:

DINIT wiE initialize a formatted diskette so that it may be used in the QNX file
system environment. The default values are determined from the current configura¬
tion of the specified drive. This configuration can be changed with the MOUNT
command.

The prefix (if specified) is the name of the "root" of the file structure on that drive.
The default prefix is which allows any directory names to be placed at the
highest directory level on that diskette (eg. the drive could contain the directories
/cmds, /lib, /expl, etc...). If a diskette is known only to contain one directory at the
highest level (eg. /user), then this prefix can be given. The prefix must start with a
slash (/). In practice, this option is rarely used.

Initialize a hard disk in drive 3.
Initialize a disk in drive 1.

Initialize disk in drive 1 to
have a root name of "/user".
Initialize disk in drive 5 without
pausing (perhaps a ramdisk).
Initialize disk in drive 1 on node 3.

Utilities

[DMIT]

DINIT

A diskette which is given a prefix other than 7" cannot be accessed without giving
the exact name of the disk. A user could name a diskette with a unique name
known only to himself which would prevent other users from looking at the files
on that diskette.

The -p option can be used to bypass the prompting for a diskette to be loaded.

In the case of a hard disk the DINIT should be followed by a DCHECK to remove
any bad blocks from the disk allocation bitmap.

dinit 3 +hard
dcheck 3 +mark

The +hard option is required if the disk is not a floppy or ramdisk. This option is
there to protect you against accidental typing errors which might attempt to DINIT
your hard disk.

The +suppress option is only used after a disaster which has destroyed the first
few blocks of your disk. Please read the technical note on "Recovering Your Hard
Disk".

The k= option will rarely be required. It may be used to create a bitmap which is
smaller than the physical disk. This will prevent QNX from touching blocks at the
end of the disk.

dinit 1 k=252 - 28 tracks * 2 heads * 9 sectors

reserve inner 12 tracks

DINIT may be used to initialize a disk on another node. The disk may be indicated
explicitly via a [node] prefix or implicitly by specifying a remdisk which you have
mounted.

See Also:

DCHECK MKDIR

FDFORMAT MOUNT

[DINIT]

Utilities

DIR - Display directory tree

Syntax:

dir [directory] [options]*

Options:

+count - Display a count of the number of files in each directory.

-files - List only directories, not files.

-t-modified - Display any directories that contain modified files with the
enhanced video attribute ( or with a preceding character
for output devices without enhanced mode ). The only files
that will be listed while this option is in effect will be those
that are modified. Thus, a command like

dir 3:1 +m

will create a display of the complete directory tree and only
those files that have been modified since the last backup will
appear within the tree.

Do not sort the output.

Maximum number of sub directories allowed in a single
directory. The program will halt if there are too many. The
default is 60.

Sets the maximum number of files that will be printed within
a single directory. The error message "too many files" will
appear if more are present. The default is 650.

Limit the depth of the directory tree. Default is 9999.

Specify a pattern to select which files are listed. This pattern
match facility applies only to file names and not to directory
names and is applied only to files that make it through the
flag settings, such as the -{-modified flag. The ’ A ’ character
can be used to negate the pattern match.

Amount of memory (bytes) used to store directory and file
names while processing. The default is 25 Kbytes.

This option can be used to manually specify the output
width. The default width is 80. This is useful when printing
a directory with -f files to a 132 column printer.

Examples:

-sort

d =max_dirs
f=maxjiles
1 =levels

p=[ A ]pattern -

m=memory

w =lim width -

Utilities

[DIR]

DIR

dir

dir 3:/ w=132 >$Ipt

dir +m +c 1=2

Description:

This utility displays a hierarchical view of the directory system. If no directory is

named5 the directory tree from the current directory down is displayed.

The output of this command uses the tcap library for the line drawing characters
and can thus be used to print directory trees on the printer or attached terminals as
well as on the screen.

See Also:

CD LS

FILES PWD

[DIR]

Utilities

DMARK - Mark bad blocks on a disk

Syntax:

mark drive [cylinder,head]*

Options:

drive - Which QNX drive is to be marked.

cylinder - Which Cylinder is bad.

Values range from 0 to T-1.
head - Which head, or platter is bad.

Values range from 0 to H-l.

Examples:

dmark 3 40,4 250,2 500,0 - mark track 40, head 4

and track 250, head 2
and track 500, head 0

dmark 3 20,1 >3:/bad_blks

Description:

If your hard disk was shipped with a sheet of paper containing a list of bad tracks,
then you may use the DMARK command to explicitly mark the blocks on these
tracks as un-usable.

DMARK will display a list of QNX block numbers on the screen corresponding to
the bad blocks. This may be re-directed into a file, which can be used by
CHKFSYS to update the bitmap on that disk.

If DMARK is used immediately after using DINIT on a new hard disk, you could
direct the output into the file /bad_blks on that disk. The DCHECK and CHKFSYS
utilities will then maintain that file as new bad blocks are discovered.

The DMARK command takes a list of cylinders and heads. Each pair is separated
by a space, with the cylinder and head separated by a comma.

Note that even if only a single block is bad, the entire track is sacrificed. This is
because interleaving of sectors on the disk locates blocks in different places,
beyond our control.

Utilities

[DMARK]

DMARK

DMARK is best used in conjunction with DCHECK, which will find any blocks
which have failed since the disk was originally manufactured.

See Also:

CHKFSYS

DCHECK

DINIT

FDFORMAT

MOUNT

[DMARK]

Utilities

DOPEN - Display open devices

Syntax:

dopen [node]

Options:

node - The node whose devices you wish to query.

The default is your local node.

Return Value:

Number of devices open
-1 on a critical error.

Description:

DOPEN will print out the names of any tasks which have a device open for read.
It does not list tasks which have a device open for write only. This command is
frequently used to determine who has the modem port open.

DOPEN only lists the devices open on one node at a time. It defaults to your
current node. You can specify a node using the node option.

dopen 4

See Also:

FOPEN

Utilities

[DOPEN]

OREL

OREL - Release Directory

Syntax:

drel directory

Examples:

drel /test

drel /user/bill/catl

drel 2:/user
drel [2]3:/user

Description:

DREL will remove a directory from the disk. Only empty directories can be

released. If the DREL command verifies that the directory is empty, then the space
used by the directory will be reclaimed.

If a directory is to be removed which is at the top level (root), it is usually
necessary to specify the correct drive prefix as in the last two examples.

See Also:

FREE

RMDIR

[DREL]

Utilities

DUMP - Dump the contents of a file in hexadecimal format

Syntax:

dump file [start_ojfset [end_ojfset]]

Options:

start ^offset - First byte to display (decimal)

default: 0.

end_offset - Last byte to display (decimal)
default: last byte of the file.

Examples:

dump test.o - Dump an entire file,

dump core 0 120 - Dump the first 121 bytes of "core",

dump $tty3 - Dump data from $tty3 (At least 80 chars

need to be sent before being displayed).

Description:

DUMP will display the exact contents of a file, 16 bytes per line (hexadecimal),
with the ASCII equivalent (if printable) displayed to the right of die line. If the
ASCII character is non-printable, it is replaced with a dot (.).

DUMP is useful for displaying non-text files such as object files and core files.

The start and end offsets are specified as decimal numbers.

See Also:

SPATCH

Utilities

[DUMP]

DUMP_IBM - Make a hardcopy of Graphics Screen

Syntax:

dumpibm [options]*

Options:

devicejiame - Name of printer to use if not $lpt.

+highjes - dump high resolution screen (640 x 480)

+m ediumjres - dump medium resolution screen

Examples:

dump_ibm - Make hardcopy of graphics screen.

dump_ibm [7]$Ipt - Make hardcopy on node 7’s printer.

Description:

This command will make a hardcopy of the IBM colour graphics screen onto an
IBM compatible graphics printer.

It is typically called from other programs (such as BAR) to print the graphics
screen since issuing the command by hand would alter the display.

See Also:

BAR

MOUNT

Utilities

[DUMPJBM]

EC - Execute a shell file

Syntax:

ec shellJUejtame

• This is a local shell command «

Description:

The EC command causes the shell to temporarily take its input from the indicated
file. Since the execution of commands in the file is performed by the current shell,
it is possible to execute commands like CD, PATH, PRI, PROMPTT etc..., which
affect the environment of the shell which executes them.

This is especially useful in the password file where you will often see a line such
as

ec userinit

EC commands cannot be nested.

See Also:

Utilities

[EC]

ECHO - Echo arguments to standard output

Syntax:

echo [ arguments ]*

Examples:

echo Hello world!!!

echo abc >$tty3

Description:

ECHO will echo its arguments to the terminal. ECHO is used within command
files to display progress information. The last argument will be followed by a

-TC /I* - jCU_

wtii i idge-ieium/ ime-ieea.

Unlike TYPE and STYPE, the output of ECHO can be redirected since it is a
executable program and not a SHELL command.

See Also:

STYPE

TYPE

[ECHO]

Utilities

EO - Execute On

Syntax:

eo [file] "command '’ [options]*

Options:

+concat - Each line in the input file is concatenated

and separated by a space. The indicated command
is called only once with multiple arguments
rather than many times with a single argument
-error - Don’t stop if a command returns back a non-zero

status. This includes a command stopped via break.
Q=offset - Skip this many characters at beginning

of each line before executing,
p ^pattern - Skip any line which does not match

this pattern (before applying o=).

+repeat - This is only used in conjunction with the +concat

option. If during concatenation of the input
lines into multiple arguments the maximum line
size of 256 characters is exceeded, then the
command will be executed with as many items on
the line which will fit. This process is repeated
until there are no input lines left or line
greater than 256 characters is read.

+verbose - Display commands as they are being executed,
dc =del_char - This character when present in command

will delete the last character of the current,
pathname (default is a backquote)
pc =path_char - This character when present in command
will be replaced by the current pathname.

If omitted, then the argument will be
appended after the command. Note that the
pathjchar is consumed by the first argument
when used with the +concat option.

(default is an at-sign @)

Examples:

eo my files "list -b" +c

Utilities

[EO]

- List all files named in my_files

eo cfiles "ed @" +v

- Edit all files named in cfiles
files -v p=*.o | eo "frel" +c +r

- Release all files ending ".o"

Description:

EO, like WS, is a utility which increases the power of existing QNX commands. It •
takes a command and a file containing a list of filenames with one filename per
line. The command will be executed once for each line in the specified file, with
the line being appended as an argument to the command. Given a set of filenames,
EO allows a convenient mechanism of executing a command across all those files.
The file list will typically be generated using the editor or from the output of the
FILES command.

files >cfiles p=*.c -v

eo cfiles ’’crypt key <@ >@.z’’

If thzfile of filenames is omitted, then me filenames will be read from the standard
input. This allows EO to be used as a filter in a pipe. The above command could
be shortened to a single step as

files p=*.c -v | eo "crypt key <@ >@.z"

Some commands are capable of accepting multiple arguments. In these cases it is
more efficient (and sometimes necessary) to execute the command once with many
arguments rather than many times with one argument. The +concat option will
take each input line and concatenate them together, separated by spaces. The
command will then only be executed once. For example

eo my files "size" +c

The +repeat option handles the case where the number of input lines when
concatenated will exceed the maximum line size of 512. In this case the command
will be executed with as many items on the line which will fit. This process is
repeated until there are no input lines left, or a line greater than 512 characters is
read.

[EO]

Utilities

EXPL - Explain

Syntax:

expl [command [ subcommand ]* ] [options]*

Options:

in -menu
p -lines

Examples:

- Force QNX display character set and
escape sequences to be used.

- Go immediately to indicated menu item.

- Pause after this many lines,
default is 24. p=0 disables pausing.

exp! inform m=B

expl led command summary p=0 >$lpt

Description:

The EXPL command provides a convenient method of indexing into the directory
of files found under the directory "/expl".

The explain files provide detailed information about commands. If the required
explain file cannot be found, but a file called "index" is present in "/expl", EXPL
will ask if an explain index is wanted. If the user responds with ’y\ then the file
/expl/index is printed (if it exists). Typing "expl index" on the command line will
also print this file.

The disk containing the directory "/expl" must be inserted into one of the disk
drives before using the EXPL command. EXPL searches for an explain command
as follows.

expl mail

/ex pl/mail

/cmds/mail.Silp

/expi/mall/expl

/expl/index

look here first
then here
then here
look here last

Utilities

[EXPL]

EXPL

In many instances, the user may only wish to be reminded of die syntax of a
command. All QNX commands explain their own syntax when the command is
followed by a single question mark.

expl ?

You may use lines containing a formfeed (Ctrl-L) to cause EXPL to pause for

input. Upon receiving a carriage return the screen will be cleared and EXPL will
continue.

The expl command will strip all escape sequences which apply to the system
console when output is redirected. The +qnx option can be used to force the
sequences to be printed when the user is logged in to QNX via a modem on a PC
using QTALK.

It is possible to construct a file which implements a single level menu using
EXPL. The file will consist of a menu followed by two formfeeds on a line by
themselves. Following this will be one section terminated by two formfeeds for
each menu section. Each section may contain several single formfeeds to cause
EXPL to pause at appropriate places. A formfeed may be entered using ED by
typing a Ctrl-L.

FF - one formfeed

text

. - this section contains a menu

FF FF - two formfeeds

text

. - menu item or 9 a 9 or 9 A 9 or FI

FF FF - two formfeeds

text

. - menu item 9 2 9 or 9 b 9 or 9 B 9 or F2

Please refer to the file /expl/inform for an example of a menu driven explain file.

[EXPL]

Utilities

fbackup [drive] INit max-numr-files [c=360K 1720K11.2M 11.4M]

["v=voljiame"]

[f=formatjcommand] [-format]

fbackup [drive] Files [archjlir] [+summary] [+|-verbose] [options]*
fbackup [drive] NAme

fbackup [drive] SAve save_spec* [+all] [-clr] [1 -levels] [options]*

fbackup [drive] REstore [disk_dir[,arch_dir]] [-create] [options]*

fbackup [drive] YErify [disk_dir[,arch_dir ]] [options]*

save_spec: disk_dir[,arch_dir] x-indexJile filename[,arch_dir]

options: +pause -verbose -multi_sector +hst-only + write

pf =[\filej)attern pd=[]dirjpattern pp =[]pathjpattern
-fbefore d -dd-mm-yy t-hh:mm:ss (Use digits)

+Force (allow use of non-floppy disks)
g-group m-member
e-errorJile

”v=volumejiame" (Use quotes if name contains spaces)

Description:

The FBACKUP command is used to archive large files to one or more floppy
disks. This command was created to solve the need for saving files which are
larger than a floppy disk (such as files used in most data base applications. Each
time a file is saved it is appended to the end of the archive which may span many
diskettes. Earlier versions of the same file will NOT be overwritten. You may
restore any version of a file on the archive.

The FBACKUP command should not be used as a general substitute for the
BACKUP command. Performing an archive of all files which changed each day
will rapidly consume large quantities of disks due to duplication.

[FBACKUP]

Utilities

FBACKUP

When saving a smaller number of files, FBACKUP is dramatically faster than
BACKUP and does not suffer the problems of disk overflow. FBACKUP will
prompt for new disks as required. If FBACKUP is being used with the 4-Force
option that allows archiving to hard disks, the CRON utility should also be
investigated, as CRON can cause this backup to automatically occur overnight.

There are many options for this command and to properly use it, the Floppy and
Tape Backup technical note at the back of this manual should be read.

See Also:

BACKUP CRON TBACKUP
Floppy and Tape Backup Technical Note

Utilities

[FBACKUP]

FBFORMAT - Format floppy diskettes

Syntax:

fdformat drive [options]*

Options:

f '-firstjrack

1 -heads

1 -lastjrack

m-sectors! track

$-stagger

t -tracks

-stagger

+patch

-pause

+other

b=sector_base
+hard
+abort

+360k
+720k

+1.2meg
+1.4meg

Examples:

fdformat 2 - Format diskette in drive 2

using defaults.

fdformat 1 +1.2 - Format 1.2M diskette in drive 1

- First track to format (default: 0).

- Number of heads

(default 2).

- Last track to format

(default: last track on drive).

- Number of sectors per track
(8, 9,10,...).

- Stagger factor (sector interleave)
default stagger is 3 for n=8

4 for n=9,10
2for n=15.

- Number of tracks on diskette
(40 or 80 for diskettes).

- Suppress the staggering of sectors.

- Write the diskette size information
indicated by h=, n= 9 1= onto block
one of the diskette.

- Suppress the prompt to load the
disk.

- Not a QNX style disk ("other”) - do not put the
QNX size information in block 1.

- block number to start sectors at. Usually 1.

- Allow formatting of an AT hard disk.

- Abort on error.

- Assume 360K floppy (h=2, n=9, t=40).

- Assume 720K floppy (h=2, n=9, t=80).

- Assume 1.2M floppy (h=2, n=15, t=80).

- Assume 1.4M floppy (h=2, n=18, t=80).

[FDFORMAT]

Utilities

•FDFORMAT

overriding defaults.

fdformat [3]2 t=80 - Format 80 track diskette

in drive 2 of node 3.

fdformat 3 +h s=6

- Format partition mounted as disk 3
with a stagger factor of 6.

fdformat 3 -fti s=6 f=l 1=152

- Format first 153 tracks of
hard disk 3 with a stagger
factor of 6. Skip track 0.

FDFORMAT allows diskettes to be physically formatted using the floppy disk
controller hardware. New diskettes must be formatted before they can be read or
written to by the disk hardware. In addition, a newly formatted diskette will
typically have to be initialized using the DINIT command before it can be used by
the QNX file system, unless DCOPY is being used to make copies of already
initialized diskettes.

CADAD 11A A HP AlcArczlri'cs thk&k AvAttol if

r JL/ Jr wlvIVI/\ i Will lomial Ulw QIoJkCLLC dwwUi U-lllg tU liUVv Uiv mi I VC kb wUIIQlllj

MOUNTed. You can override the defaults by specifying parameters to the
command. Floppy disk drives have three physical parameters of interest. The
number of sides (single or double), the number of sectors (8, 9, 10 or 15) and the
number of tracks (40 or 80).

The t -tracks option allows you to format a diskette with 40 tracks or 80 tracks.
Note that 80 track floppy drives are mechanically different than 40 track drives.
You can read a floppy diskette formatted with 40 tracks on an 80 track drive by
double stepping, but you can NOT format or read an 80 track diskette on a 40 track
drive.

The n-sectors!track option allows you to format a diskette to hold more or less
information than the default size. For example a 360K floppy diskette (40 tracks, 2
heads, 9 sectors/track) can be formatted to hold 320K or 400K by specifying n=8
or 11=10 sectors/track. This option is independent of whether the drive is single
sided or has 40 or 80 tracks. You should use high quality floppy disks if you use 10
sectors/track. A value of n=15 may only be used on special high performance
drives which may contain 1.2 Meg (2 heads * 80 tracks * 15 sectors/track).

Utilities

[FDFORMAT]

FDFOEMAT

The following table may clarify things.

Sectors/Track

Sides

tracks

160K

180K

200K

+300K

320K

*360K

400K

+600K

320K

360K

400K

+600K

640K

720K

800K

+1200K

* - Default If no parameters are specified
+ - Requires high performance AT disk drive and
special high capacity floppy diskettes.

This formatting information is encoded on the diskette and is queried each time a
file is opened. This allows QNX to read differently formatted diskettes in a single
drive without having to remount the disk. This encoded information overrides
those that are specified by the MOUNT command. Diskettes formatted with
VERY old versions of FDFORMAT (QNX 1.1), or perhaps other operating
systems will not contain this encoded information. In this case the defaults
specified by the MOUNT command will be used. You may use the +patch option
to place the mount information on a diskette which for one reason or another does
not contain it. The disk will NOT be re-formatted.

The -stagger option disables the staggering of sectors formatted on the diskette.

By staggering sectors by 3, a program will have two sector times (about 12 msec)
to process one sector of data and still be able to read the next sequential sector on
the same revolution of the disk. Although this slows down program load time from
the disk, it can significantly increase program throughput!

FDFORMAT may be used to format a floppy disk on another node. The disk may
be indicated explicitly via a [node] prefix or implicitly by specifying a remdisk
which you have mounted.

Hard disks may be formatted if the +hard option is specified and the hard disk
driver supports formatting.

See Also:

DCOPY

DINIT

MOUNT

[FDFORMAT]

Utilities

FDBSK _

FDISK - Create QNX disk partition

Syntax:

fdisk drive

Options:

drive - Disk drive to partition.

FDISK allows you to partition a hard disk. The partition information matches that
used by DOS. It is kept on the first physical block on the disk.

IMPORTANT: FDISK must only be used when the file system is idle. No
other users or programs can have open files when this utility is used.

To create a QNX partition for the first time you must first mount a hard disk
driver. For example:

mount disk 3 /drivers/disk.xt

This is explained in a technical note in your QNX manual. You do not need to
specify an offset or size. You should now execute the FDISK command from the
floppy.

fdisk 3

and partition your disk. QNX does NOT automatically mount any partition. Once
you have created the partition, you should remount the disk using this partition. For
example:

mount disk 3 /drivers/disk.xt pa=qnx

[FDISK]

Utilities

FDISK

Specifying the pa= option will cause the MOUNT command to read the partition
block, locate the first QNX partition, then mount the drive with the correct offset
and size. You will probably wish to place this mount command in your sys.init so
that it is executed each time you boot. If you are running the QNX-DOS file
system task, you may also wish to mount a DOS partition as another drive. For
example:

mount disk 4 d=3 pa=do§

Note that you should NOT remount the driver. The d= option indicates that the
existing driver which has already be mounted for disk 3 should be used.

It is important to realize that the FDISK command only displays and updates the
partition information on the disk. It does NOT directly affect your access to the
drive. You must still issue the MOUNT command separately.

FDISK is a full-screen, interactive program which is fairly self explanatory. When
fdisk is invoked, it will display a screen similar to that shown below:

Ignore

Prev Change Delete Mount

Boot Unboot

Save Quit

start

End

Number Boot

name

type

Cylinder

Cylinders

Blocks

—> 1 .

dos

( 1)

139

140

19039

qnx

( 7)

140

279

140

19040 *

qny

( 8}

280

419

140

19040

qnz

( 9)

420

639

220

29920

Use up/down

arrows

: to select

partition.

Type the letter c to change/add a partition.

Type the letter s to save your changes.

Type the letter q to quit.

QNX is os type 7, 8 or 9 DOS is os type 1 or 4 Unused is os type 0

First cylinder is 0 Last cylinder is 639
Disk is 44,564 , 480 bytes H-8 T=640 N=17

Utilities

[FDISK]

FDISK

The Possible commands are displayed along the top line. They can be selected by
typing the first letter of the command, or by moving the cursor to the appropriate
command (with the arrow keys), and typing Enter.

The commands are described below:

BOOT

Make the selected partition the boot partition.

CHANGE

Change the selected partition. You must input an OS type, a start cylinder and an
end cylinder.

DELETE

Delete the selected partition.

IGNORE

This menu item does nothing. It is a safeguard against accidental carriage returns
which select the current menu item.

MOUNT

Display the parameters which you would give to the MOUNT utility for this
partition.

Select the next partition. The down arrow key may also be used.

Select the previous partition. The up arrow key may also be used.

QUIT

Leave the FDISK command. Remember to Save first, if you have changed
anything.

SAVE

Save any changes made to the partition back to the disk. Unless this command is
executed, your changes will be ignored. This allows you to quit without saving if
you mess things up.

UNBOOT

Clear the boot indicator from the selected partition.

NOTE: If you wish your disk to contain both QNX and DOS partitions? be
sure to create the DOS partition FIRST (using DOS)

[FDISK]

Utilities

FDISK

See Also:

MOUNT

Utilities

[FDISK]

FILES - List Files

Syntax:

files [ directory ] [options]*

Options:

-fbusy - Display only files which are busy.

+directory - Display directories instead of files.

+current - Only display files at the current level.

+modified - Display files which have been modified

since the last backup.

“Sort - Don’t sort filenames.

-used - List files which have been FRELed or ZAPped.

-verbose - List only the name of each file.

+verbose - List detailed information about each file.

+totals_only - Only print totals of blocks and files.

t=hh:mm:ss - Only print files which have a date later than
this time on the given date.

d=dd-mon-yy - Only print files which have a date later than
this date.

+Before - Applies to the t= and d= options.
a=[& I A ]attr_list

- List files whose attributes correspond to attrjist
where attrjist is one of maewrc.
p -pattern - Only display files whose name matches

this pattern.

Examples:

flies

files /cmds -s
files +v

files 3:/a=&rw

files 3:1 a= A w
files +d -v >lndex

files 3:1 p= : Lc +v

files 3:1 d=10-06-90

List files at current directory.

Unsorted list of files in /cmds.

List ALL information on files
at current directory.

List all files which have the READ and
WRITE attributes set.

List all files which are not WRITEable
List directories, don’t sort, then
place output in the file index.

List files on drive 3 which end in .c.

List files with dates later than 10-June 1990.

Utilities

[FILES]

FILES

Description:

The FILES command allows the user to list the files at or below any point in the
file structure. If no directory is specified, then the current directory is listed. The
FILES command will walk the entire tree structure recursively, displaying all files
at the specified (or current) directory followed by all files at lower levels. The +c
option prevents the recursive walk of the file "tree", causing only those files at the
current level to be displayed.

Normally, file names will be sorted before being displayed. This feature can be
turned off by specifying the -s option, in which case file names and directories will

be displayed in the order they are found. When sorting, files at the current
directory will be displayed first, followed by any files at lower levels in the
directory.

Directories are just special files in the QNX file system. The Files command will
normally not print directories. If the user wishes to examine the directories which
exist at this and lower levels, he can use the +d option. The ~s and +c options apply
to directories as well as to files.

If desired, only files whose filename matches a pattern may be displayed. The
pattern is specified using the p= option. A pattern can be any valid filename, and
may include the following wildcards:

* matches any run of characters

? matches any one character

[ ] will match any of the characters enclosed in the square brackets

An example pattern which will match any file which ends in ".c" or M .h" is
"p=* [ch]".

The +v option can be used to display the information about each file which is kept
in the directory. One line of information will be displayed for each file, with the
filename displayed last. The following information will be presented:

Blk - Number of disk blocks in the file (512 bytes per block)

X - Number of Extents in the file (indicates degree of disk

fragmentation). A contiguous file will consist of one extent.

Loc - Starting location of the file (hex block number)

Grp - Group number of file owner. (1... 255)

Mem - Member number of file owner. (1... 255)

Attr - Attributes of the file. These are the access methods permitted for the
owner of the file (or the super-user and privileged commands)
Perm - Permissions. These are the access methods available to users other
than the owner of the file. G-perms apply to other members of the
same group. O-perms apply to to all other users.

[FILES]

Utilities

FILES

Date - Date that the file was created or last changed.

Time - Time that the file was created or last changed.

Name - File name (relative to the specified directory). As deeper levels of

the file structure are displayed, the complete hierarchical pathname is
displayed.

Attributes and Permissions for FILES may be:

r MEAD permission. The file can be read.

w WRITE permission. This file can be written to. User programs can

therefore change the file contents and even delete the file (since null files
are removed)

a APPEND permission. The file can be written to, but only new information
can be added to the end of the file. The file cannot be deleted.

e EXECUTE permission. This file can be executed. If the file contains
executable code, it can be executed directly. If instead it contains text, then
the file will be treated as a command file, and the text lines will be given to
the shell for interpretation.

m MODIFY permission. This allows the permissions and attributes of the
file to be changed (using CHATTR)

Attributes and Permissions for DIRECTORIES may be:

r READ permission. The directory can be read (listed).

c CREATE permission. New files may be created under this directory.

b BLOCK access. Prevent any files or directories below this directory from
being accessed.

m MODIFY permission. This allows the permissions and attributes of the
directory to be changed (using CHATTR).

d DIRECTORY. The file is a directory.

If a file is BUSY, it will be flagged in the attribute column with a ’B’ character.

The FILES command is a very useful tool for creating command files. A typical
use of this function could be in the generation of a command file which is to delete
all of the files at and below the current directory level. The user could start by

typing:

files “V >command

which would create the file "command" containing a list of all the files at and
below the current directory level. He could then edit this file and substitute the
beginning of every line with "frel ", and save the file away:

led command "*s/ A /frel/" w q

Utilities

[FILES]

FILES

He could then execute the command file by typing:

si command

This example might be tetter accomplished using either the wild card syntax 'of the
shell or the WS command.

frel *

ws "frel 1=12

A tetter use for such a file is on the creation of an index file for commands like
LIST and LINK which support the x=index option. These commands expect to be
provided with an index file of the form created by the FILES command.

See Also:

CHATTR

LED

■ LS

[FILES]

Utilities

Syntax:

fopen [node j [+uscriaj

node - The node whose files you wish to query (default is your node),

+eserid - Display a userid instead of the program which has a file open.

Return Value:

The return status is the number of files open
or -1 on a critical error.

FOPEN will print out the names of any tasks which have a file open. It not only
indicates the program which opened the file, but also the open mode and the
current location within the file. The location can be used to judge a programs
progress in processing a file by invoking FOPEN several times. The location is
shown as two numbers as follows:

current Mock / last Mock

This command can be used in a shell script r,o check if any files are open before

shutting the system down.

fopen

if lie #? 0000 type "You have #? files opera Do not shut down the system,"

FOPEN only lists the files open on one node at a time. It defaults to your current
node. You can specify a node using the node option.

fopen 4

See Also:

DOPEN

[FOPEN]

Utilities

FREE

FREL - Release File

Syntax:

fre! file [file]*

Examples:

frel junk

frel staff oldjunk test©
frel [2] 1:/config/sy s.init

Description:

FREL will remove a file from the disk. The space esed by that file is reclaimed for
use by other files, and the directory entry is removed. One or more files can be
specified on the command line.

If the file exists at the 'root of a disk, or if the same directory exists on multiple
drives, then the filename should be preceded by the correct drive prefix to remove
ambiguity. For example, use:

frel 3:/test

to remove the file "test" from the top level of the disk in drive 3.

See Also:

DREL

RMDIR

Utilities

[FREL]

FSTAT

FSTAT - Display file status

Syntax:

fstat file* [+xtnts]

Options:

file - A QNX filename.

•f xtnts - Display the disk extents which
are allocated to this file.

Description:

In its simplest form, FSTAT can be used to display die date of one or more QNX
files.

fstat /user/luc/testx

fstat *.c

If the +x option is used, then FSTAT will also give a complete list of all the disk
blocks which are allocated to this file. This option is a useful debugging tool.

See Also:

DIR

FILES

[FSTAT]

. Utilities

GREP - Search a file for a pattern

Description:

Please refer to the documentation on the LOCATE command.

See Also:

LOCATE

Utilities

[GREP]

KBD - Redefine keyboard layout

Syntax:

kbd khdjype [f-userjile]

kbd list [i=user_fiie]

Options:

kbdjype - Keyboard type to use
list - List all keyboard types

f-userjile - alternate file to use (default: Iconfigl kbd Abase)

Examples:

kbd 102.GE

kbd 84.FR f=/eonf!«?/kbd.db.ours

kbd list

kbd list f=/config/kbd.db.ours

Description:

The KBD command remaps the character codes that are produced by your
keyboard, using a binary data file {Iconfigl kbd Abase). You will only need to run
this command if you are using a non-US keyboard. Users who require this
command will likely execute it in their sys.init files.

To find out what keyboard remappings are available, use the list option. The
naming convention for a keyboard remapping is number Jceys .country _code
where number Jceys is the number of physical keys on your keyboard, and
country_code is typically a two letter abbreviation for a particular country.

First, you need to figure out which keyboard you have. Specifically, you need to
determine number Jceys. The simplest method is to count the number of key caps
on your keyboard. Following is a brief description of each keyboard, and a picture
of the default character mapping for it.

Utilities

[KBD]

KBD

Below is the IBM PC/XT 83 key keyboard. It has ten function keys along the left
side, and an integrated numeric/arrow keypad on the right side.

■

BSP

TAB

]

SFT

SPACE BAR

CAPS

Below is the original IBM PC AT 84 key keyboard. It has ten function keys along
the left side, and an integrated numeric/arrow keypad on the right side.

' 1

TAB q

u !

CTRL

SHIFT

ALT

SPACE BAR

CAPS

Below is the "enhanced” 101 key keyboard. It has twelve function keys along the
top, and separate numeric and arrow keypads on the right side. It was first avail¬
able on the IBM PC AT, and later used on the IBM PS/2. This keyboard is only
available with the US keyboard layout.

' 1

BSP

TAB

[

]

CAPS

j ;

;

ENTER

SHIFT

CTL

ALT

SPACE BAR

ALT

CTRL

[KBD]

Utilities

KBD

Below is the "enhanced" 102 key keyboard. It has twelve function keys along the
top, and separate numeric and arrow keypads on the right side. It was first avail¬
able on the IBM PC AT, and later used on the IBM PS/2. This keyboard is only
available with non-US keyboard layouts.

' 1

BSP

TAB

[

ENTER

CAPS

;

SFT

SHIFT

CTRL

ALT

SPACE BAR

ALT

CTRL

Once you have determined which physical keyboard you have, you need to
determine which character remapping to use with it. Following is a current
alphabetical list of the abbreviations for country_code, and their meanings.

Belgian

Canadian French

Danish

Dutch

French

German

Italian

Latin American

Norwegian

Portugese

Swedish

Swiss

Spanish

United Kingdom

United States

If you do not specify an alternate file using the f= option, the file
/config/kbd.dbase will be used. You may create an alternate file by copying the
original /config/kbdAbase file, and possibly modifying the copy using the
KBD_EDIT command, which is available from the update service. The f= option
allows a user to avoid having their modified keyboard layouts overwritten by an
updated /config/kbd.dbase file from QNX Software Systems Ltd. The keyboard
remappings in /config/kbd.dbase should be accurate, and thus this option should
rarely be used.

Utilities

[KBD]

KILL

KILL - Kill a task

Syntax:

kill task-id

® This is a local shell command 9

The indicated tasks will be killed. You may obtain the tasks identity with the TSK
command. KILL is supported by the shell to allow you to kill a task even when
there are no free task descriptors in the system to create a new task. The escape
sequence #& refers to the last background task you created.

wii m

If the first argument starts with a plus sign (+) it is taken as a system exception to

set on the remaining taskid’s specified. For example

kill +0001 050c -set exception hangup on task 050c

Refer the to chapter on MULTI-TASKING in the QNX manual for more informa¬
tion on exceptions.

You may wish to refer to the SLAY command to remove a task by if s name
rather than if s task id.

See Also:

BREAK "
SLAY

[KILL]

Utilities

KILL VC

KILL VCS - Kill all virtual circuits to a node

Syntax:

kill vcs nodejd

Options:

nodejd - Node number of crashed node.

Examples:

kill_vcs 3 - Kill virtual circuits to node 3

Description:

The KILL__VCS command will kill all virtual circuits between your node and a
node which has crashed. This allows manual recovery without using the poller.
Please refer to the QNX manual on setting up your network.

If a poller is running somewhere on the network, then this command should not be
needed.

See Also:

ALIVE

POLL

TSK

Utilities

[KILL_VGS]

LED - Line Editor

Syntax:

led i file [commands]}

Examples:

led

lei junk

led testx *s/b£ll/joe/ w q

Description:

The editor is a line oriented text editor which supports a number of powerful
pattern matching facilities. Only text files can be edited, which means any files
containing regular ASCII characters on lines which are terminated with a newline
character (hex IE). Null characters (hex 00) are not allowed within the file.

Lines are numbered sequentially starting from 1. Line numbers change
dynamically as new lines are created and lines which are not needed are deleted.
Lines can be referred to by specifying the line number explicitly, or relative to the
current line (which is referred, to by the character "."). A line can also be referred to
by specifying a partem of characters which is found on that line. Some commands
support ranges of lines, which may begin and end with line numbers, relative line
numbers, or lines containing patterns.

Files are edited by first reading the entire file into a memory buffer. This provides
for a very fast editor, and minimizes the dangers of having files open while editing.
Unfortunately, very large files cannot be handled by this editor. It is recommended
that large files be divided into several smaller files before editing.

Files can be inserted anywhere into the editing buffer with the "r" command, and
portions of the buffer can be written to any file (default being the current working'
file).

[LED]

Utilities

LED

Features supported by the editor are:

- insertion before a line

- append after a line

- delete line(s)

- write a group of lines to a file

- append a file after the current line

- character substitution on a range of lines

- global command execution on a group of lines

- join two lines

- print a group of lines

- change current line

- location of lines containing patterns

- moving a range of lines to another position

- copying a range of lines to another position

Editor Command Syntax :

The format of an editor command is typically of the form:

linerange command parameters

where:

command is the command character (described below)
parameters are arguments to the command

linerange is the range of lines which are to have
the command applied to them.

linerange can be:
line

or linejine

or *

line can be:

lineno

Ipatter nl

line+nn

line-nn

Utilities

[LED]

LID

The characterrepresents the current line. The character "$" represents the last
line. The character represents ALL lines which is the same as "1,$". The
character represents hie lines from the current line to the current line plus page

size (ie. one screen).

Patterns represent a line which is found to contain that pattern. Patterns enclosed in
slashes (/) mean the next line AFTER the current line which contains the pattern.
Patterns enclosed in question marks mean the closest line BEFORE the current line
which contains the pattern, scanning backwards. In both cases, scanning wraps
around the beginning and end of the file and will terminate when the current line is
again reached.

Example line numbers and lineranges are:

- line 3

1,10

- lines 1 to 10

- the current line

.+25

.-10,.+5 '

- 25 lines past the current line.

- all lines from 10 lines before the current

line to 5 lines past the current line

- the next line which contains the string "joe 1

- all lines from line 1 to 4 lines past the next

/joe/

1,/loop :/+4

line containing the string "loop:"

1,$

- all lines

Editor Patterns :

The text editor allows pattern arguments to be used when locating line numbers,
and when substituting strings.

Several metacharacters are used when specifying a pattern, these are:

A - represents the null character at the beginning of a line

$ - represents the null character at the end of a line

. - matches any character

[ccc] - where V can be any characters, will match any one of the enclosed
characters, (eg. [abc] will match any of "a", "b", or "c"

[c-e] - where V is any character, will match any of the characters in the

range of ASCII characters, (eg. [a-z] will match any letter)

[ A ccc] - where "c" is any character, will match all characters EXCEPT those
in the square brackets

@(nn) - which represents the null character before character position nn.

[LED]

Utilities

LED

Any of the above pattern characters may be followed by a star (*), which means
zero or more occurrences of that pattern character, (eg. "a*" will match a null
character, a, aa, aaa, etc.... ".*" is useful in matching a run of any characters)

Preceding any character (including the metacharacters) with a backslash (\) will
indicate that that character is to be taken literally, (eg. "\*" will match the character
and 'W will match the character 'V).

All other characters in a pattern are treated literally (ie. they will match only that
character.

Examples:

will match "abc" anywhere in a line
will match "abc" at the beginning of a line
will match "abc" at the end of a line
will match any character followed by "abc"
will match any run of characters followed
by "abc" '

will ixi&icn every tiling on a line
will match the largest run of characters
consisting only of numbers (which may
be the null string)
will match a number
will match the largest run of characters
which does not contain the digits 1, 2 or 3

In string substitutions, two patterns are specified separated by delimeters, (eg.
s/fred/bill/ or s,ed/,edit/,). The special metacharacter ampersand (&) is used to
represent the portion of the line which was matched by the first pattern. This
allows some very powerful editing operations.

For example:

s/[0-9][0»9]*/<&>/ - will turn the line "123 men on 3 horses"

into the line "<123> men on <3> horses"

s, A .*$,copy & dir/& 5 - will turn the line "junk.c" into the line
’’copy junk.c dir/junk.c"

When these pattern substitutions are combined with the global command (g), some

very powerful editing operations can be performed.

/abc/

/ A abc/

/abc$/

/.abc/

/.*abc/

/A *<£/

/[0-9]*/

/[0-9I0-9]*/ -

/[ A 123]/ .

Utilities

[LED]

LED

[line] a - Append new input after the line.

End with a line containing
a single ".*’

[range] ' c - Change these lines to new input.

End with a line containing
a single

[range] d - Delete these lines

efile - Edit new file...delete all lines,

read in new file,
and change current file name,
f [file] - Change current file. If no file,
then display current file name.

[range] g!pattern! commands

- Globally execute these ed commands
on this group of lines.

[line] i - Insert new input before the line

End with a line containing
a single

[line] j - Join this line with the next line.

[range] Mine - Make a copy of these lines

behind the indicated line.

[range] m line - Move these lines behind

the indicated line.

ocl char - Defines the command-line prompt

character to be this char,
oclchar - Defines the input prompt to be
this char.

oc3char - Defines the character to print when
a null-line is entered.

od - Dual-case is recognized in patterns,

odr - Dual-case not recognized.

Upper and lower case are the same,
of - Display special symbols in expanded

formNhh where "hh" is the hex value
of that character.

ofr - Turn off expansion of special symbols,

op number - Define page size (for
mnumber - Auto-save into file ’’autosave” after
this many lines has been entered
in input mode.

ov - Display error messages upon error,

ovr - Turn off error messages. Only display

error number.

[range] p - Print these lines.

q - Quit if file not altered.

[LED]

Utilities

LED

qq - Quit anyway.

[line] r file - Read the file and put in buffer AFTER

this line.

[range] s/pattern/newl

- Substitute aU occurrences of this

pattern for the new pattern within
this line range.

[range] snumber/pattern/new/

- Substitute the Nth occurrence of the
pattern,

[range] \/pattern/commands

- Execute the ed commands on all lines
EXCEPT those with this pattern,

[range] w [file] - Write these lines to the file

& - Print a page (size defined by

"op" command).

[line] - - Display this line number (eg. ".=").

CR - Display next line.

Utilities

[LED]

LINK

LINK - Link object files

Syntax:

link [o=new_object_file] objfile* [options]*

Options:

+i - Intel addressing mode (default).

+m - Motorola addressing mode.

+v - Verbose.

m-mapfile - Create a map and put in mapfile.

o-obj jile - Create a new object file,

u =sym - Use the symbols found in sym

but do not include the code or data.
sl-hhhh - Segment 1 starts at hhhh (hex).

§ 2 -hhhh - Segment 2 starts at hhhh (hex).

s3=hhhh - Segment 3 starts at hhhh (hex).

s4-hhhh - Segment 4 starts at hhhh (hex).

sl=$n - Segment 1 starts AFTER segment n.

s2=$n - Segment 2 starts AFTER segment n.

s3=$n - Segment 3 starts AFTER segment n.

s4 =$n - Segment 4 starts AFTER segment n.

s-stack - Increment to minimum stack size.

c -loadfile - Put output file into loadfile
(default is "core”).

x-index - Link the object files in index.

\-library - Search directory library for

any unresolved functions and variables.

A file named '7/&rary/directory" must be found
which lists symbols defined in each object file,
n -namelen - Maximum length of a name (default: 66).
b -bufsize - Size of symbol buffer (default: 32000).

Examples:

link /Itb/eetryaO test.o

link x=edfl!es ra=.map. !=/lib s=4000

link o=ed.o x=ofi!es +v

link u=rom.map rom.o m=map sl=ffc0 s2=1000 s3=$2
link o=$nulI test.o +v

[LINK]

Utilities

LINK

Description:

The routine CC should be used instead of LINK for linking programs to run on
QNX. CC will invoke LINK with the proper arguments to create a load file for the
QNX environment. Any arguments to CC are passed on to LINK. The same is
true for any extra arguments passed to the CC command. LINK may be called
directly to link programs for environments other than QNX.

The Linker will link together object files which are created by one of the compilers
or the assembler. A load file is produced which is in a form to be executed directly
(by typing its name on the command line). All external references are resolved, and
warning messages are printed if any object module references a symbol which is
not defined in any other module.

The default values for the 4 segments which are allowed by the assembler are such
that if no overriding values are specified, the command will execute properly.
Overriding segment starts and offsets are typically only used when linking together
object files which are not to be executed as a command. For example, a program
which is to be placed in ROM would need to be linked outside of die default
memory segments.

The x= option accepts a file list in the form which would be created by the FILES
command, allowing convenient linking of commands which consist of a large
number of object files. Therefore the format of an index file is with one object
filename per line.

The 1 = option invokes a search for unresolved symbols under the specified
directory. A file named "directory" is used to define the contents of this library of
object files. The format of this file is one object file name on a line by itself,
followed by any number of lines which begin with a TAB character followed by
one symbol which is defined in that object module (see the file "/lib/directory" as
an example). Any number of object files may be described in the library file.

" Multiple 1 = options are allowed so that many libraries can be searched. All library
references must be forward. Refer to the documentation on QNX compilers in
your C binder for more information.

Program execution begins with the first address in segment 1 which is typically the
code segment.

By default, all commands are given a IK stack by the operating system. The s=
option in the linker allows additional stack space to be allocated.

The linker will create a map file if the m= option is used. This map is useful when
debugging programs. The address (hex) of all functions and variables is included in
the map. Typically the map should be sorted with the SORT command if it is to be

Utilities

[LINK]

LINK

used in debugging a program.

sort mapfile s=l,3 +r (sort by name)

sort map file s=l,2 +r (sort by address)

The linker can take a collection of object files and combine them into one large
object file using the o= option. It must immediately follow the LINK command.
The sl=» s2=, s3= and c= options are not used.

link o=ed.o main.o command.© output.o input.o +v

Note that this option may be used to determine the size of an object module. In
this case the output is thrown away.

ink ©=$ftull objfile.o +verbose

There is no limit to the number of object files which can be linked together
provided that the resulting command will fit within the address limitations of the
processor (64K code + 64K data). If the code segment is exceeded, you will need
to refer to the the technical notes in the C Compiler binder.

LINK maintains its symbols in an allocated buffer. This buffer defaults to 32,000
bytes, but may be changed with the b= option. If LINK complains that it has ran
out of symbol space (for very LARGE programs), try again with a bigger buffer. If
memory is tight on your machine, you may wish to decrease this value. Valid sizes
are 2000 to 65,520.

See Also:

ASM CC

SORT Technical Notes (C)

[LINK]

Utilities

LIST - List files on the line printer

Syntax:

list [options]* [file]*

Options:

b-banner

d-device

i=file

l-page_length

n -name.

Q-offset
p-port

s =vert_spacing
w~line_width
t =tab[ 9 tab]*
n-indexjile

+numberlines

preset

+gap

+assembly

+listing(assembly)

4-emphasized

-emphasized

+double_print

-double_print

-pagination

-header

+banner

+user

Examples:

- Name of banner on first page.

- Name of $device to use for output
(default: taken from prt.init).

- Printer configuration file
(default: /cmds/prt.init).

- Define page len in inches (default 11).

- Name to print in header
(default: filename).

- Offset from left hand margin.

- Define semaphore port (default 16).

- Vertical spacing (lines per inch).

- Characters per line.

- Define tab stops.

- File containing list of files to
print.

- Print line numbers with listing.

- Reset page number to 1 for new files.

- Feed a gap for a new banner.

- Set tabs for assembly source program.

- Set tabs for assembly listing.

- Turn on emphasized printing.

- Turn off emphasized printing.

- Turn on double printing.

- Turn off double printing.

- Turn off pagination (and headers).

- Turn off header (date and page no.).

- Print a banner page.

- Print user numbers on each page.

list test.c

list s=8 w=80 o=10 report

Utilities

[LIST]

LIST

list +a ,f n=ASM Files" x=assembly_index

list +g

list +b -p -h w=80 s=6 +e gooddocument

files +¥ | list &

Description:

LIST provides a means of printing paginated output on a line printer. The date,
time, filename, and page number are printed at the top of every page. More than
one file can be specified on the command line. Index files may also be used which
contain a list of files to print with the current option settings. More than one index
file can be specified. The format of an index file is that of the output of the FILES
command (with the -v option).

Tabs are expanded into spaces by the LIST program. The default tab stops are at
every 4th character position. This can be changed with the t= option. If more than
one tab stop is given, then LIST will assume that tabs past the last specified tabstop
will have the same spacing as the gap between the last two given tabstops. For
example "t=4,7" will put tab stops at position 4,7 and then every 3 positions
afterwards since the difference between the last tabstop (7) and the previous one
(4) is 3 spaces.

For printers which support different line spacings, the s= option allows the user to
select the line spacing (eg "s=6" for 6 lines per inch, "s=8" for 8 lines per inch).
Some printers also support different character widths. Character widths can be
changed using the w= option. Examples are "w=80" for 80 characters per line and
"w=132" for 132 characters per line (on an 8 1/2 inch page).

Some printers (such as the MX-80) allow special print modes such as emphasized
printing (use +e) or double printing (use +d).

If listings are to be placed in binders, a margin is often desired on the left side of
the page. The o= option will offset all output the specified number of spaces to the
right to leave such a margin.

When used with the banner option (+banner) the first page of a listing contains a
"banner" which gives the current date and time as well as the name of the first file
being listed. A different banner can be specified with the b= option. In this case the
LIST program will always feed enough spaces after the last file has been printed to
allow the user to remove his listing without needing to feed the paper himself. The
resulting gap is used by the next LIST command for its banner. This mechanism
works well provided that the user only uses the LIST program to generate output
on his line printer. To initially position the paper at the correct position for printing
banners, the user should position the paper to the top of a new page, then issue a
"list +g" command which will feed the proper number of spaces. Subsequent LIST

[LIST]

Utilities

LIST

commands will then be positioned properly. This procedure is especially useful for
printers which don’t support formfeeds.

The LIST program also provides a means of turning off the printing of the top-of-
page header (-h), and/or the automatic spacing between pages (-p). This allows the
user to print documents which don’t require these features, but still be able to
specify line spacings, print modes, etc.

The LIST command will automatically wait for other LISTs to finish before
printing. This automatic spooling is especially useful in multi-user installations
where many users wish to print files at the same time. So long as everyone uses
LIST to print their files, the listings will not be mixed together.

The characteristics of the line printer are found in the file 7cmds/prt.init". This file
name may be over-ridden using the i= option. If no configuration file exists, then
the LIST program assumes that it is talking to a printer which prints 80 characters
per line at 6 lines per inch. An example format of the file 7cmds/prt.init n is shown
below for the EPSON MX-80 printer. All numbers are decimal unless followed by
the character ’IT or ’H’ in which case they are hexadecimal. These numbers often
represent ASCII characters. Note that the comments in the following example
should not be included in the file.

$lpt

name of printer (may be overridden using d=)

form-feed character (0 if not supported)

132

default width for listing (characters per line)

default spacing for listing (lines/inch)

default width for headers

default width for banners

default spacing for banner page

WIDTH #1 (characters per line, 8 1/2" page)

20 18

string to print to cause this line width

132

WIDTH #2

20 IS

string for width #2

END of widths

SPACING #1 (lines per inch)

27 50

string to print for spacing #1

SPACING #2

27 48

string for spacing #2

END of spacings

27 69

string to print for +e

27 70

string to print for -e

27 71

string to print for +d

27 72

string to print for -d

[LIST]

Utilities

LIST

See Also:

p ■

SPOOL

[LIST]

Utilities

LOCATE - Locate patterns of characters in a file

Syntax:

locate " pattern " [file I x=file]* [options]*

Options:

c-context
b-bytesJo _skip

w~pattern

x-file
+dualcase
+count
“Verbose

Examples:

locate array teste

locate INV main.c support.c x=index junk.c +d
locate "([a-zJta-z]*)" *.c -v

Description:

LOCATE will find patterns of characters in a given file (or files). The name of the
file, and line number will be displayed along with the entire line, for each line in
the file which contains the pattern. Patterns are the same as those used in the LED
command.

Index files may be used to avoid typing long strings of file names on the command
line. The format of these index files is the same as the output format of the "files
-v" command.

Consider a directory called /application which contains several C source programs,
and perhaps several object files as well. To find all the C source files which
contain a call to the function "sort", the user could use the following:

files /application -v p=*.c >index
locate sort( x=index
OR

locate sort( *.c

- Number of lines to print for each match.

- Number of bytes to skip before starting the locate.

- After a match continue output while following
lines match pattern.

- Index file containing list of files to search.

- Distinguish between upper and lower case.

- Exit with number of finds.

- Don’t display filename and line number.

[LOCATE]

Utilities

LOCATE

This will produce one line of output for every occurrence of the pattern "sort(" in
all these files. The LOCATE command will also supply the filename and line
numbers where these patterns occur. The WS command is often used with locate
for the same purpose.

ws "locate sort( p=*.c

Normally, upper and lower case letters are treated identically. The user can specify
+d which will then distinguish between upper and lower case letters.

The -v option turns off the display of filename and line number at the beginning of
each output line.

The w= option permits simple lookup databases to be implemented with simple
text files created by the editor. For example, a file could be created with keywords
followed by lines of descriptive text which are indented by one or more spaces. To
print the text associated with a keyword "QNX”, one could issue the following
command:

locate A QNX "w= A " -v

The LOCATE COMMAND can be used in SHELL scripts to count the number of
occurrences of a string in a file. The +count option is useful for this.

The c= option allows some context to be printed around each matching line. For
example, specifying c=5 would print each line containing the pattern, along with
the next 4 lines (5 lines of context ). The c= and w= options cannot be used at the
same time.

See Also:

FILES

LED

Utilities

[LOCATE]

LOCKER - Implement record locking In QNX

Syntax:

locker [options]* &

Options:

s-cachejize - Number of IK blocks to allocate for the cache. Default Is 64,
minimum is 32, maximum is 1000.

p -port - Port to attach to. Used for timing purposes to age the cache,

h-bujfers - Maximum data segment buffers to be used.

f-files - Max number of simultaneous open files.

+d ebug - Internal use only.

+sync - Force 0_SYNC option on all OPEN()’s. (See the C compiler

manual for details)

Description:

LOCKER implements a record locking facility in QNX. To make use of it,
applications must have been written specifically to use LOCKER. LOCKER is
usually started from the sys.init at boot time, and left running always. The
b-buffers option us used to set the number of data segment buffers to be used by
LOCKER (max approx 30). The larger this value the less room there is for locks,
task entries etc.

If you need to terminate LOCKER, use the SLAY command:
slay locker

Although no QNX Software Systems applications are using LOCKER (as of
January, 1988), this may not always be true. However, a number of 3rd party
applications (notably database products) are using locker. If you have any doubt as
to whether or not you should run locker, check the documentation for the applica¬
tions you wish to run, or contact the vendor or QNX Software Systems’ technical
support.

LOCKER requires the presence of TIMER. Before starting LOCKER, you must
invoke TIMER (it is used to age the cache). For example:

timer &
lockers=100 &

Jtilities

[LOCKER]

LOCKER

See Also:

TIMER

Record Locking in QNX in the C manual Technical Notes

[LOCKER]

Utilities

userid - Name of user: (Max 16 characters).

password - Unique password for that user.

(Max 20 characters).

+stack - Stack logins, freeze current user.

Examples:

Description:

LOGIN allows a user to log-in to a QNX system. QNX will invoke LOGIN on the
console automatically when the system boots. LOGIN will also be invoked if a
user types Ctrl-Z on any idle terminal or console.

If invoked with no arguments (such as with automatic invocation by QNX),
LOGIN will prompt the user for his user-id and password. The user will be greeted
with a message of the form:

QNX version x.xx (Release x)

The user-id supplied by the new user is checked against all valid user-ids found in
the file 7config/pass\ If a match is NOT found, then LOGIN will re-issue the
message:

[LOGIN]

Utilities

If the user-id DOES match one of the entries in the password file, then LOGIN
will prompt the user for a password:

Password:

This password must match the one found in ’/config/pass’. If it does not, then
LOGIN will re-issue the login message. If the password was found to be correct,
then LOGIN will create the user. The user’s number (group.member) is assigned
from the password file, as is his home directory. An initial command is also
executed automatically, if one exists in the password file. Finally, LOGIN will
create a SHELL on the terminal for the user to use.

Once a user has successfully logged-in, he may use LOGIN to log-in to another
user. If +stack is not specified, then LOGOFF will be called automatically. If a
valid user-id and correct password are given to LOGIN, then that user will be
logged-in without prompting for these values. If both fields aren’t supplied (or are
incorrect), then LOGIN will issue the login prompt and wait for a valid user-id.

See Also:

LOGOFF

QNX Manual

Utilities

[LOGIN]

LOGOFF - Terminate a QNX Session

Syntax:

logoff [-Z]

Options:

-z - Don’t print message regarding Ctrl-Z.

Examples:

logoff

logoff -z

Description:

LOGOFF is called by a user to terminate Ms session with QNX, All resources
which were used by the user will be reclaimed by the operating system and his

accounting entry will be deleted.

If the -z option is not specified, a message of the form:

......... Type a Ctrl z to login ———

will be displayed to remind the next user of that terminal to type a Ctrl-Z to log in.

See Also:

QNX Manual

[LOGOFF]

Utilities

LPS - List Postscript Laser Printer Filter

Syntax;

lps [file]* [options]*

options: +align +(crt) 4-duplex 4-Duplex 4-header 4-landscape

4-Landscape +pchars 4-verbose +quad 4-Quad +octal +Octal

SL=alignfactor[44Q] K-align_char c=columns[l] f-font[4]
{-ignoredjpages k -copies l-maxlines n-pagesjo_print
Q-offset O-offset p =cur_psize[ 12] r -rightmargin
s=extra_spacing sx=x_scale sj=y_scale

+align

+(crt)

+duplex

+Duplex

+header

4-landscape

4-Landscape

4-pcfaars

4-verbose

4-quad

4-Quad

4-octal

4*Octal
a -alignfactor

- Turn on auto-alignment feature.

- For each letter entered, map that letter when enclosed by
parentesis into the symbols (• c)->© , (• r)->® and (• t)->™ .

- Print two pages on one physical page in landscape mode. The
logical pages are scaled, rotated and translated to fit.

- Same as 4 -d except the page offset is applied to the logical
page printed on the right side of the physical page.

- Display the filename as a header on each page printed.

- Rotate the logical page to print sideways on the physical
page. If more than one column is printed the page offset is
only applied to the first column.

- Same as 4-1 except the page offset is applied to each extra
column printed when t-columns is specified.

- Support the codes for the PC line drawing characters. These
characters are defined in the file /config/pcfoetps.

- Print a comma (,) for each logical page skipped and a period
(.) for each logical page printed. Remember that several
logical pages may be printed on one physical page.

- Print four pages on one physical page in portraite mode. The
logical pages are scaled and translated to fit.

- Same as 4-q except the page offset is applied to the logical
pages printed on die right side of the physical page.

- Print eight pages on one physical page in landscape mode. The
logical pages are scaled and translated to fit.

- Same as 4-0 except the page offset is applied to each logical
page.

- Set the width of the alignment character in 100 * points. The

Utilities

[LPS]

LPS

A=align_char

t-columns

f=font

i=numpages

k=copies

l=maxlines

n-numpages

^-offset

0 =ofjsei
p -points

r-rightmargin

s=spacing

s upscale
sj=scale

Examples:

default is 440.

- Two character hex value which represents the alignment
char. The default is the backquote C)> hex 60.

- Select the number of columns to place on a physical page.
Each logical page starts a new column.

- Select the font to start printing with. It defaults to Times
Roman.

- Ignore (skip) this number of logical pages. Note that several
logical pages may print on one physical page (ie: +dual,
c=columns ...).

- Number of copies to print for each page. The default is 1.

- Force a new logical page after receiving this number of lines.
Useful when text is pre-formated without formfeed
characters.

- Only print this number of logical pages. Note that several
logical pages may print on one physical page (ie: +dual,
c=columns ...).

- Specify a page offset (left margin) in points. Defaults to 36
points (1/2 inch).

- Same as o= except the offset is applied to all columns and not
just the first column.

- Select the pointsize to start printing with. This set the
‘ pointsize for a logical (full size page). The +dual and

+quad options scale it. It defaults to 12 point.

- Specify a right margin in points. Used for justification only,
lines are not broken. Defaults to 468 points (6 1/2 inches)
from left page border.

- Specify extra points (1/72 inch) of space between printed
lines.

- Floating point number to scale charcater width. Do not use
with the +d or +q options.

- Floating point number to scale character heigth. Do not use
with the +d or +q options.

lps text o=72 >$mdm

lps text +d >$mdm

lps text +q >$mdm

lps text +1 c=4 f=0 p=8

lps text +1 c=4 f=0 p=8 sx=,75

Description:

[LPS]

Utilities

LPS

The LPS utility takes a text file and converts it into a set of postscript commands

which will display it on a laser printer supporting postscript. There are a number
of command line options which provide considerable flexability in the formating of
the output. The utilty also recognizes a large set of escape sequences which can be
embeded within the text to further enhance your output. For example, there are
sequences to changes fonts, pointsize, attributes and underline to mention only a
few. These escape sequences allow word processors and the QNX list command
which do not support postscript to be used with a postscript laser printer. To find
which fonts are supported by LPS type.

Ips ?

Note: Your printer may support fewer or more than those fonts listed.

The size tables for all these characters are kept in the file /config/PSwidths.
Programmers may use these tables for their word processors. It is structured as

struct font_entry {

char font jnarae[32]
unsigned font_widttis[256]

} font_fiie[NUM__FONTS];

with each value containing the characters width at pointsize 1000. Keeping the
width as scaled integers saves the application from having to use floating point
which is much slower. LPS also uses the following two files.

/config/Prolog.ps - Pre-peeded to each job.

/config/LineChars.ps - A Sine drawing character set.

If you are familure with Postscript, you may edit and modify these files. In
particular you may wish to add to the line drawing character set.

LPS takes as input a series of logical pages and from them produces one or more
physical pages. A logical page is what you would consider to be a full page of
text. The end of a page is usually marked by a formfeed character or the end of
file. If your text does not separate it pages with formfeeds but instead expects the
printer to start a new page every nn (say 66) lines then you can specify a 1=66
parameter to LPS to cause it to paginate based on this number. If your pointsize is
too large for a logical page to fit on the physical page LPS will itself break the
page when you run off the bottom. This allows you to take a completely
unformated piece of text and run it through LPS without any options knowing that
it will be paginated properly reguardless of the pointsize used. If you text contains
formfeeds and you select too large a pointsize LPS will paginate on page overflow
then again when it sees the formfeed character resulting in a second page which
contains only a few lines of text. In this case you should reduce your pointsize.

Utilities

[LPS]

LPS

Unlike a daisy wheel or dot matrix printer which maps one logical page to one
physical page, the LPS utility can map several logical pages to one physical page.
It does this by scaling the text, and then translating it to different area’s of the page
instead of starting a new page. For example the +quad option puts 4 logical pages
onto 1 physical page by scaling the x and y size by 0.5 and treating the physical
page as 4 small pages by translating the output. The mapping looks like this.

This has two advantages, for drafts it saves paper and on a 7 page/minute laser
printer you can often achieve 20 logical pages/minute throughput. Each logical
page displayed will also look the same as that produced when you go for a full
page master of each logical page. The +dual option rotates the page and placed 2
logical pages on one physical page. Each logical page is the same size as used in
our manuals. When producing a master for a printer it is best to produce pages at
full size and have the printer reduce them when he makes the plates. In the case of
pages of the size you are now reading this reduction has the side effect of
increasing you laser printers resolution from 300 dots/inch to over 400 dots/inch.

[LPS]

Utilities

UPS

For those with good eye sight there is also a -foetal mode which prints 8 logical
pages per physical page. The output is still quite readable (heh, heh) and if your
laser printer can keep up, you can print at an effective rate of 8 times your laser
printer’s page output rate.

You can also place mutiple logical pages on the physical page by using the
^columns option which will divide the page into the indicated number of
columns. Each logical page will start at the start of the next column. In this case
you have to select a pointsize which fit the text in the columns. Scaling is NOT
performed automatically as it is with the dual and qaud options. You can also
specify landscape mode to rotate the page. The options of +1 and c=3 would
produce a physical page of.

Physical Page

The + dual and f quad options start the logical pages which are printed on the right
side of the physical page exactly at in the middle. The page offset is only applied
to the left side. If you specify a capital letter (+D, +Q) then the offset will be
applied to the right side as well. In the case of dual printing this provides for a
margin if you wish to cut the page in half and place it in a binder.

+dual option

+Dual option

When producing tables with a variable width font they seldom line up. Each
character has a differrent width. You can force alignment by adding a backquote.
The +align option can be used to automatically add them for you. However, it
makes certain assuptions and guesses which may not be what you want. When
enabled, for each line LPS reads it will add them after a run of two or more spaces
not preceeded by by a., ? or! and around dashes (-) and o’s (o) which are often

Utilities

[LPS]

used for points.

aiaiaia - Without alignment char on any of

these lineSo

axaxaxa - Without alignment char on any of
these lines.

aiaiaia. - With alignment chars on each side

of the dash (**) and the start of
text on each these lines,,

axaxaxa - With alignment chars on each side
of the dash (-) and the start of
text on each these lines.

Please note that a space is a very narrow character while a capital A is very large.
Alignment is based upon an average which assumes that all characters are about
the width of a small a. This will be true on average but fails badly when presented
with all capitals. The line.

AAAAAAAAAAAA "point one

will actually slide the text "point one" to the left resulting in an overprint as
follows:

AAAAAAAAA|yiilt one

This can be corrected by simply increasing the number of spaces before the point.

AAAAAAAAAAAA ‘point one

which produces

AAAAAAAAAAAA point one

You can use simple shell files to interface utilities like LIST to your laser printer.
For example, the following shell file is suitable for producing listing of C programs
on your laser printer. To conserve paper it prints with the +dual option and uses
the courier font. Note that you will have to create a list initialization file which
uses the escape sequences supported by LPS.

list #* >/tmp/#n#t.lst i=/config/psinit
Ips /tmp/#n#tlst f=0 +d >$mdm

[LPS]

Utilities

LPS

If this file was called LLIST you can use it in place of LIST.

llist filel.c f!!e2.c...

Your laser printer is going to be very popular and you will want to share it amoung
many users. This is most easily acomplished using the SPOOLER and SPOOL
command. If your printer is attached to $mdm you should run the spooler as
follows.

spooler "crdps >$mdm ,, t=/tmp/ &

You may wish to place this command in your system initialization file. You can
now submit files using the SUBMIT command.

spool su file any Ips options

In the example of the LLIST shell command above you would replace the second
line with LPS to a SPOOL SUBMIT command.

Escape Sequences

In the following tables some of the escape sequence take one or more ascii digits as
parameters. They will be represented as italic (T s.

d - A single digit.

dd - Up to 2 digits.

did - Up to 3 digits.

dddd - Up to 4 digits.

If several digits are expected you can supply fewer as long as you terminate them
with a non-digit. For example if dd was expected then input would be interpreted
as

Ixyz - Read a 1 followed by "xyz"

12xyz - Read a 12 followed by "xyz"

123xyz - Read a 12 followed by "3xyz"

123xyz - Read a 12 followed by ?? 3xyz"

You may also enter a leading plus or minus sign to indicate a relative rather than
an absolute change.

ESC p 12 - Set pointsize to 12 points.

ESC p +3 - Add 3 to current pointsize.

Utilities

[LPS]

LPS

ESC p -3 - Sob 3 from current pointsize.

There are two classes of escape sequences, single character and muti-character.

The multi-character sequences always start with an ESC code (hex lb, dec 27).

You will note that LPS supports the escape sequences supported by the system

console. A file which highlights, underlines ... text on the console will do the same
on the laser printer. Inverse is mapped to italics and blink to larger characters.

The console colour escape seouences are ignored

Note that center, fully justify and right justify are easily remembered by there first
letter with a control key. The text following these codes extendes to another code
or a code which forces a repositioning of the text (typically a newline).

Single Character Sequences

Name Ctrl Hex Action

TAB Ctrl i 09 Move to next tab stop. Tabs fixed every 4.

MS Ctrl A le Move to start of next line.

CM Ctrl m Od Move to begining of this line.

LF_ Ctrl j 0a Move down a line (same column). .

ETX Ctrl c §3 Center following text between margins.

ACK Ctrl f 06 Fully justify following text between margins.

DC2 Ctrl r 12 Right justify following text between margins.

ETB Ctrl w 17 Force a current position (moveto command) to printer.

EOT Ctrl d 04 Ignored and striped from the text.

FF Ctrl 1 0c End of a logical page (formfeed).

The following will create a line with three parts. One part left justified, one part
centered and one right justified. Text in < >’s represent a single character.

UtI!If?es<ETX>© QNX Software Systems<DC2>LPS<RS>

Multi Character Sequences

Sequence

Action

ESC (

Italics on.

ESC)

Italics off.

ESC <

Bold on.

ESC >

Bold off.

ESC [

Underline on.

ESC]

Underline off.

ESC {

Increase pointsize 1/3.

ESC}

Decrease pointsize 1/3.

ESC#

Pattern mask on.

ESC :

Pattern mask off.

ESC d

Subscript (move down 1/4).

[LPS]

Utilities

ESC f dd
ESC p ddd
ESC u
ESC m ddd
ESC 6
ESC g ddd
ESC z d
ESC z 4 cmd „
ESC o ddd
ESC a d
ESC F d
ESC M ddd
ESCS
ESC R
ESC b dd dd
ESC y ddd , dtfdf

Set font.

Set pointsize in points.

Superscript (move up 1/4).

Set right margin In points.

Display the quote char.

Set gray level. 0 (black) to 100 (white).

Add zing to text. 0 to 3 supported.

Use postscript command to show text.

Set page offset in points.

Set aiito-align ©e (d=t) or off (</=0).

Expand mask (Esc # 9 :) to right margin if d=h
Manual feed the next ddd sheets of paper.

Save font, pointsize, attributes and zing.
Restore from last save (ESC S).

Draw a box. If gray level != 0 then it Is filled.
Move by points by x (col) and y (row). This
is usually done as a relative move.

The following sequences impliment the console cursor movement escape
sequences. To be useful you should use the courier fixed point point. Proportional
fonts may not line up as expected.

Sequence
ESC A
ESCB
ESC C
ESC D
ESCB
ESC Y cc

For special situations you may pass postscript commands directly to the laser
printer by enclosing them in the follow escape sequence.

SYN SYN postscript commands SYN

Action

Cursor up.

Cursor down.

Cursor right
Cursor left.

Cursor home.

Direct cursor addressing.

In conclusion, the following escape sequence can be used to create the shaded
blocks with which each of our utilities start with. You will have to supply a 2 digit
number for you right margin (margin) and the text to be outlined (your text).

Both need to be provided twice. The right margin is provided in character posi¬
tions NOT points. The last two lines of the escape sequence vary depending on
wheather you wish an odd or even page.

Utilities

[LPS]

ESC S ESC B

ESC g 095 CR ETB ESC b margin +04
ESC g 000 ESC b margin +04

ESC A

Odd page (right justify)

ESC ff08 ESC p +20 ESC g 100 DC2 your text CR
ETB ESC g 000 ESC z 1 DC2 your text ESC R

Even Page

ESC f08 ESC p +20 ESC g 100 your text CR
ETB ESC g 000 ESC z 1 your text ESC R

See Also:

SPOOL

SPOOLER

Save state and position
Draw shaded rectangle
Draw box outline

Position

Put text in white
Put text in outline

[LPS]

Utilities

LS - List directory

Syntax:

Is [directory] [options]*

+modified -sort p=[ A ]pattern +unused -dir_off 4-dir_on
+age_sort +Size_sort +reverse_sort +size +blocks -All

c—columns -columns_off -*-file_list ^horizontal +'verbose

+executable -executable +Modified_only +clear_screen
w- column_width +tx_time b=baud_rate -modified 1 -linejength

Examples:

Is +v

Is /cmcls

Is /user/bill/dirl -s
Is +M p=*.c +c

Description:

LS displays a sorted list of all the files and directories which reside at the current
(or specified) directory level. Directory names are preceded by a plus sign (+)
indicating that there is a substructure below it.

There are an almost unbelievable number of options:

- Highlight files that have been modified since last backup.
These files are shown with enhanced video mode or with a
leading star (*) if enhanced is not available. The other files
are also shown.

- Show only files that have not been modified since last
backup. Setting this flag also supresses the display of
directories.

- Show only those files that have been modified since last

backup. Setting this flag also supresses the display of
directories.

- Supress all sorting of the output. Files appear in the order in

which they exist in the directory file.

- List all file entries which are unused. These files may be

+modified

-modified

+Modified

-sort

+unused

Utilities

[LS]

LS'

-All-

+directories

-directories

+age__sort

+Size_sort

+reverse_sort

+size

+blocks

c -columns

-columns

+file_list

+horizontal

+verbose

+exeeutable

-executable

+elear_screen

w -width

Inline Jength

recoverable if they were recently deleted.

- Don’t list all files. Files beginning with a character will be
excluded from the file list.

- Directories on. List only directory files in the output.

- Directories off. Do not include directory files in the output.

- Sort by age (most recent first) rather than by file name,

- Sort by file size (largest first) rather than by file name.

- Reverse the sort order to get reverse alphabetic, oldest first, or
smallest first, as appropriate.

- Show file sizes. This mode is active whenever verbose mode
is turned on. If verbose is off, then the file size display must
be selected with this flag.

- Show block counts. If file sizes are being displayed, this flag
will cause the file size to be displayed in blocks rather than
in bytes.

- Used to manually set the number of columns in the output.

If the number of columns is set to a large number, then a
stream of file names will result. A column setting of 0 has no
effect.

- Turn all multi column output off. This forces the output to be
displayed as one column. This has the side effect of asserting
horizontal output mode, which forces the after each file
name is output.

- Display a list of files, excluding any directory files, modified
notation or file sizes in one column. This command is
synonymous with "Is -v -c -d +h" and is used as a short hand
notation for it. This option is useful to prepare lists of files
for other commands to process. Executing "Is +f p=*.[ch]" is
a quick way to get a list of all the source files in a directory.

- Horizontal file list. This causes the file names to be listed
across the columns rather than down the columns.

- Display the output complete with directory name, file sizes
and a usage summary.

- Executable files on. List only executable files in the output.

- Executable files off. Do not include executable files in the

output.

- The screen is cleared before the directory is displayed.

- Used to manually set the width of the columns in the
output. Changing the column width causes the number of
columns displayed to also be recalculated. This recalculation
can be supressed by manually setting a column count with
the c= option. A column width of 0 is quietly ignored.

- Used to manually specify line length. This is useful for
sending the output of this command to a printer that may
have a 132 or 240 character line. Also useful for squeezing

[LS]

Utilities

+tx_time

b =baud rate

p -{^pattern

See Also:

DIR

the output onto a 40 column screen if necessary.

- Used to cause the transmission time of a file to be displayed.
The default baud rate used for this calculation is 1200 baud.
The b= option can be used to specify a baud rate. While Ms
mode is active, directory display is turned off.

- Used to manually set the baud rate used for transmission
time calculations* If a b= option is specified on the command
line, the time display mode is automatically selected without
+t having to be specified.

- List all files matching the pattern described. This pattern
match is applied to die files that make it through die flag
settings. For example, if the -d option is set, even directory

files which match the pattern will not be included in the

output. The ’ A? character can be used to negate die pattern

match. Character ranges can be specified in the form [a-e].
This would be expanded to [abcde] for matching purposes.
Multiple ranges and die ’ A? option also work. Filename

patterns can be any valid filename, with the following
"wildcard” characters:

* will match any character, or run of characters

? will match any one character

[ccc] will match any of the characters in the brackets

Some examples of filename patterns are:

p=* *

any

p=*.[ch]

any

p=?a

any

p=[a»e]*

any

p= A *.o

any

file with a dot (.) in it.
file ending in ’c’ or ’h’
two character filename ending in ’a’
file starting with ’a’,’b’, ’c’, ’d’ or ’e’
file which doesn’t end in ’.o’

FILES

PWD

Utilities

[LS]

MAKE - Maintain and recreate files

Syntax:

make [target I option 1 macro jdefinition] *

Options:

f-filename - Use filename as the description file. The default is makefile
or Makefile in the current directory.

-{-print - Print the complete set of macro definitions, rules and

dependency descriptions.

+ignore_errors - Ignore error codes returned by invoked commands.

-verbose - Do not print command lines before executing.

-execute - Print all command lines (even those beginning with an "@")

but don’t execute them.

-{-touch - Change the dates of the target files instead of executing the

usual commands.

-{-unconditional - Ignore the file dates (assume every target file and dependent
is out of date) and recreate everything,
d -directory - Change directory to directory before doing anything else.

This allows MAKE to be used recursively in other
directories.

+debug - Debug mode. Print out detailed information on files and

times examined. (This is usually used when the description
file is not performing as desired).

All other arguments are treated as target files to be "made", unless they contain

an "=" sign, in which case they are a macro definition (see the section on
macros for more details).

Examples:

make

make -e f=my_makefile
make +t x.o y.o core

Description:

[MAKE]

Utilities

MAKE

MAKE is used to maintain up-to-date versions of target files by ensuring that all of
the files on which the target file depends exist and are up-to-date. If any of the
dependents have been modified more recently than the target file, it is (re)created
using specified commands or internal rules. MAKE performs a depth-first search
of the dependencies, examining the date and time that the files were last modified.

Usage

MAKE reads a description file that defines the way that the components of a
program depend upon each other, and what commands must be executed to
recreate each component.

If no f -file option is given, the files makefile and Makefile in the current directory
are tried in order.

Description Files

A description file consists of the following information:

- macro definitions

- dependency information

- executable commands.

The basic form of a simple description file is:

dependency line
command line
command line

This may be repeated as many times as needed.

The syntax of a dependency line is one or more target file names, followed by a
colon (:), followed by the names of zero or more files on which the target(s)
depend. This can be expressed as:

target [target]* : [dependent]*

Some examples of dependency lines are:

x.o : x.c header Ji /dir/file.h
core : a.o b.o c.o

Utilities

[MAKE]

MAKE

If you wish to use a full path name for one of the targets, the colon between the

drive and path must be escaped using a backslash (\), such as:

3\:/user/„. % dependents

Zero or more command lines follow dependency lines. Command lines consist of
a tab, optionally followed by an "@" sign or a -or both (in any order), followed
by an executable shell command. The printing of a specific command is
suppressed if the command line begins with an ”@ M sign, unless the -execute op¬
tion is specified. MAKE normally terminates if any command returns an error
code, unless the 4gnore_errors options is specified, or the command line begins
with a The oris not part of the command.

The syntax of a command line can be expressed as:

tab[@\-]* commandJine

Because each command line is passed to a separate invocation of the shell, care
must be taken with certain commands (e.g. cd and shell control commands such as
path) that have meaning only within a single shell process. The effects of these
command are forgotten before the next line is executed. However, you can place
multiple commands on the same line, separated by a semi-colon (;). For example:

cd my_dir;cc myprog

All commands on a line such as the one above, will be executed by the same shell,
so cd and path commands will take effect, for the other commands on that line.

The comment convention is that a sharp (#) and all characters on the same line
after a sharp are ignored. A comment cannot be placed at the end of a command
line. Blank lines and lines beginning with a sharp (#) are totally ignored. If a
noncomment line is too long, the line can be continued by using a backslash (\) as
the last character of the line. In that case, the backslash, the new line, and all
following blanks and tabs are replaced by a single blank.

A target can appear on more than one dependency line, with the dependents on the
additional lines adding to the previously defined dependents. Although not as
useful, any commands related to the additional dependency lines also add to the
end of the list of previously defined commands for that target file.

[MAKE]

Utilities

MAKE

An example of this is:

x.o y.o: a.h
. x.o: b.h

which is the same as:

x. o: a.h b.h

y. o: a A

The following description file example says that printjsetup depends upon three
object files: printsetup.o, smalLo, normaLo; each of the objects depend upon
their source files and, in addition, print setup.o and small.o depend on the header

files setup A and printA.

# Description file for printjsetup program

printjsetup: printjsetup.o small.o normaLo
cc print setup.o small.o normaLo

printjsetup.o: printjsetup.c setupA printA
cc -c printsetup.c

smalLo: small.c setupA printA

cc -e small.c

normaS.o: normaLc

cc -c normaLc

To make the file printjsetup, assuming that the above description file is in a file
with the name makefile or Makefile, you would enter:

make print setup
or
make

The second example will use the first target mentioned in the description file
(printjsetup). It is also possible, though less common to type:

make smalLo

to only remake a single object file.

Utilities

[MAKE]

MAKE

As more features of MAKE are described, you will be shown how to simplify this
description file.

Macros

MAKE has a limited form of macro processing that includes string substitution.
Macros are defined in the description file by:

inacro__naiiie = valiie_string

Macros may also be defined in the argument list passed to MAKE. Any argument
that contains an "=" is assumed to be a macro definition, with the exception of the
f- and d= options. Special care must be exercised when defining macros in the
arguments. The following guidelines should be followed:

1) No spaces are allowed between the first 5 = 5 and the macro

name or the value.

2) When the macro definition includes imbedded blanks, the

entire macro definition should be enclosed within quotes.

3) The macro name is all of the characters before die first

and the value is all of the characters after the first

For example:

make CC=cppo "LFLAG=+v i=mylib Vf

This command will define two macros CC and LFLAG with the following values
"cppo" and "+v l=mylib".

Macros may be used in any of the dependency, command or macro definition lines
(resulting in nesting of macros) and are recognized whenever $(macro_name)
appears in the input. If the macro name is one character the parentheses are not
required. The following are all valid macro invocations:

$(CFLAGS)

$(xy)

$(Z)

pe last two invocations are identical. A $$ is a simple dollar sign ($). Care must
be taken when using macro nesting; recursion (repeatedly nesting the same macro)
is not tested for. '

[MAKE]

Utilities

MAKE

The following is an example of a use of nested macros:

HEADEES1 = xA yJi zA
HEADEES2 = aA bA cA
ALLJHEADERS = $(HEADEES1) ($HEADEES2)

There are a number of macros built into MAKE which are initialized when MAKE
is started. They may all be redefined within a makefile or on the command line.
Most of these initialized macros are used for the transformation rules (discussed
later), but two of them deserve special attention: CWD and SHELL.

The macro CWD is initialized to the current working directory in effect after
MAKE processes its command line options (to give the "d=" option time to take
effect). It is occasionally useful within command lines.

The macro SHELL is initialized to the default shell in use by the user. However,
it may be reset to indicate which shell should be used for interpreting command
lines when executed. For example, if you are using shell (user interface) other than
the default shell supplied with QNX, it may not be able to interpret certain
command sequences (such as "#u" - your userid) used in a particular makefile,
which expects that you are using the default shell. To condition make to always
use a particular shell (for example, the QNX default) instead of the user default,
include a line like:

SHELL = /cmds/sh

The previous description file example can now be simplified to:

# Description file for printsetup program

OBJECTS = printsetup.o smaiLo normal.o
HEADEES = setup A printA

print_setup: $(OBJECTS)
cc $(OBJECTS)

prin£_setup.o: print_setup.c $(HEADERS)

cc -c printjsetup.c

small.o: small.c $(HEADERS)

cc -c small.c

normal.o: normaLc

cc -c normal.c

Utilities

[MAKE]

MAKE

Invocations of macros in dependency lines are expanded immediately. Macros in
macro definitions are expanded when used. Macros in command lines are
expanded immediately before the command is executed.

A macro that has never been assigned, expands to a null string on invocation.

Macro Redirection

In QNX, it is frequently useful to have a list of file names stored in a file (an index
file). For example, a list of object files to be linked together may be stored in a file
called ofiles. However, this same list of objects may be needed by MAKE, so they
can be made before linking. To avoid the need to maintain the list in the index file
and the MAKE description file, it is possible to have the contents of a macro read
from a file. The syntax for this is:

macro = ©filename

An example is:

OBJECTS = ©ofiles

Suffixes. Implied Dependencies and Internal Macros

The only thing MAKE knows about file name suffixes, is that they begin with a
To compensate for this lack of understanding, it has an internal table of
suffixes for files which are frequently used with MAKE. As MAKE examines the
file dates and times, it also matches die suffixes in the table against the file names
to try and extrapolate from the dependencies in the description file to other
(implied) dependents. The information extracted and built is placed in a series of
internal macros.

The suffix table has the form of a dependency line where the target is .SUFFIXES
and the dependencies are the suffixes. Naturally, there are no command lines for
.SUFFIXES.

The default suffix table looks like:

.SUFFIXES: .0 .c .c~ .h ,h~ .a .a~ .y .y~ .b .b^ .exe

[MAKE]

Utilities

MAKE

where the suffixes represent:

.0 Object file . ■

.c C source file

.c^ C source file in an archive

Ji Header file

.h^ Header file in an archive

.a Assembler source file

.a^ Assembler source file in an archive

.y Yacc-C source grammar

.y** Yacc-C source grammar in an archive

.b BASIC source file

Jr* BASIC source file in an archive

.exe DOS .exe file

As QNX supports more languages, this table will be extended. MAKE will list the
internal tables, macros, etc. if make +p is entered.

Suffixes ending with a tilde (~) exist to support a source code revision control
system, that may appear in the future.

The order of the suffix list is important, since the list is scanned from left to right.
New suffixes can be appended to the table placing an entry for .SUFFIXES in the
description file, such as:

.SUFFIXES s .xyz ■ ■

/This will add the new suffix ".xyz" to the usual list. A .SUFFIXES line without
any dependent suffixes deletes die current list. It is necessary to do this to remove
suffixes from the table, or to change the order of search. An example is:

.SUFFIXES s

.SUFFIXES:' .0 .c

By reducing the number of suffixes in the table, it is possible to improve the
performance of MAKE when working with very large systems. When it is poss¬
ible to define new rules, this facility will be useful for adding suffixes for new
languages which MAKE is not already programmed to handle.

The current target file name is placed in the macro $@, and the stem (the portion
of the target file name, less the suffix as found in .SUFFIXES) is placed in $*. If
no suffix was matched to the target file name, $* contains a null string ("").

Utilities

[MAKE]

MAKE

Once a stem has been identified, in turn, each of the suffixes are concatenated to
the stem and the resulting filename is matched against the dependents specified in
the description file, to try to find the name of the "source" dependent. If an explicit
"source" dependent isn’t found, the same procedure is tried against the file names
in the same directory as the target file in an attempt to find an implicit "source"
dependent. If a "source" dependent is found, its name is placed in the macro $<,
else it will expand to a null string.

As MAKE checks each of the explicitly stated dependents, it places the names of
the dependents younger than the target file in the macro $?.

The following table summarizes the internal macros:

$@ - The target file name.

$* - The target stem (the file name less the suffix).

$< - The "source" dependent (the stem plus a suffix).

$? - The explicitly stated dependents, younger than the target.

With the search for implied dependencies and the internally maintained macros, it
is now possible to reduce the example above to:

# Description file for printsetup program

OBJECTS = printsetup.o small.o normal.o
HEADERS = setup.h print.h

print setup: $(OBJECTS)

cc $(OBJECT8)

print setup.o small.o: $(HEADERS)
cc -c $<

normal.o:
cc -c $<

Notice that the source file names are never mentioned, but are implied by the
suffixes.

When MAKE scans the arguments it is passed, the options specified (with the
exception of f=, +p and d=, the target names and macro definitions) are placed in
the internal macro $(MAKEFLAGS). This is for use with hierarchical makefiles.
See the section on Recursive Makefiles for details.

[MAKE]

Utilities

MAKE

Extensions to $*. $@. and l<

To the list of internally generated macros, the following related macros have been
added: $pF), $(*B) 9 $(@F) ? $(@D), $(<F), $(<D). The "D" refers to the directory

portion of the single letter macro. The "F" refers to the file name part of the single
letter macro. They are useful for maintaining source and objects in different
directories, or in conjunction with hierarchical makefiles, as in:

$(MAKE) $(MAKEFLAGS) d=$(<D) $(<F)

An alternative to the above, would be the line:

cd $(<D);$(MAKE) $(MAKEFLAGS) $(<F)

Both of these examples will cause MAKE to change directory to the directory
$(<D) before reading the description file and making the target $(<F). The second
example (with the cd command) will temporarily change directory at the shf 11
level. The current working directory will revert to the original directory MAKE is
being run in at the end of die line. See the section on Recursive Makefiles for
details on MAKE invoking MAKE.

Transformation Rules (Implied Commands)

If a "source" dependent (the macro $<) was identified and there are no commands
associated with the current target (the macro $*), a transformation rule is selected
based on the suffixes of the target and dependent file names. The name of the rule
is made by concatenating the suffix of the source to the suffix of the dependent (i.e.
the rule to transform a .c file to a .o file is .c.o).

Rules have the syntax of a dependency line and command line(s), where the target
name is the rule name and the command line(s) are the commands to be executed if
the rule is invoked. Naturally, a rule has no dependencies. MAKE version 2.1 and
beyond will allow rules to be redefined and new rules to be created, but this facility
is not yet supported.

The .c.o rule is expressed as:

.c.o:

$(CC) $(CFLAGS) -c $<

This means, execute the command in the $(CC) macro (default: "cc") with the
arguments in the $(CFLAGS) macro (default:""), as well as the argument "-c"
(don’t produce a core file) on the file whose name is in the macro $<.

Utilities

[MAKE]

MAKE

An example of a complex description file follows. This is the file used to maintain
the MAKE command. The only transformation rule it uses is the .c.o rule
described above. The file contains:

# Create the make command in the current directory

CFLAGS = +optimize

SOURCES=
HEADERS=
OBJECTS =

INSDJR =

main.c make.c misc.c read_file.c input.c rules.c definitions.c
manif.h struct.h extern.h

main.o make.o misc.o readfile.o input.o rules.o definitions.o

/crads

core: compiledate.o

$(LD) l(LDFLAGS) $(OBJECTS) compile_date.o

@patch core +p

install:

copy core $(INSDRIVE)$(INSDIR)/make

print: $(SOURCES) $(HEADERS)

list w=80 +r $?
chattr $@ +d s=+m

compile date.o: $(OBjECTS)

$(CC) +p -c $<

$(OB JECTS): $(HE ADERS)

make.o: /lib/task msgs.h

misc.o: /lib/io.h 7lib/!fsys.h /lib/dev.h

rules.o: /lib/accounth /lib/task_msgs.h /lib/systids.h

[MAKE]

Utilities

MAKE

The following output results from typing make in a directory containing only the
source and description file:

MAKE: cc -c definitions.©

MAKE: cc -c rules.©

MAKE: cc -c input.c
MAKE: cc -c readfile.c
MAKE: cc -c misc.c
MAKE: cc »c make.c
MAKE: cc -c main.c
MAKE: cc +p -c compiledate.c

MAKE: cc main.o make.o misc.o readfile.o input.o rules.o
definitions.© compiledate.o

Although none of the source files were explicitly mentioned in the description file
as being dependencies of the target core, MAKE found them using its suffix rules
and issued the needed commands. The printing of the patch core +p command
was suppressed by an "@" sign.

The "print" and "install" entries in the description file are useful maintenance
sequences. The "print" entry prints only the files changed since the last make
print command. A short file print is maintained to keep track of the time of the
printing. The $? macro in the command line then picks up only the names of the
files changed since the file date and time of print was changed (via chattr +d).

In the "install" sequence, MAKE can be installed into different directories or on
specific drives as follows:

make install INSDRIVE=1:
or

make install INSDIR=/free

Utilities

[MAKE]

MAKE

The following is a listing of all the internal macros and default rules:

# LIST OF SUFFIXES

.SUFFIXES: .0 .c .c~ Ji .lr* .a .a~ .y .y~ .b .b~ .exe

# PRESET VARIABLES

MAKEFLAGS=-e

MAKE=make

YACC=yacc

YFLAGS=

LD=cc

LDFLAGS=

CC=cc

CFLAGS=

AS=asm

ASFLAGS=

GET=co

GFLAGS=

CWD=3:/man/iitil

SHELL=/cmds/sh

# INTERNAL RULES

.c.o:

$(CC) $(CFLAGS) -c $<

X $(GET) $(GFLAGS) $<

$(CC) l(CFLAGS) -c $*.c

rm $<

.h-Jis

$(GET) $(GFLAGS) $@

.a.o:

$(AS) l(ASFLAGS) $< $@

’ a *°* $(GET) l(GFLAGS) $<

$(AS) l(ASFLAGS) $< $@

rm $<

s y.c:

$(YACC) $(YFLAGS) +d $<

$(YACC) l(YFLAGS) +d $<
$(CC) $(CFLAGS) -c $*»e
rm $*.c

[MAKE]

Utilities

MAKE

.y~.o:

$(GET) $(GFLAGS) $<
$(YACC) l(YFLAGS) +d $<
$(CC) $(CFLAGS) -c $*.c
rm $*«c $<

.b.o:

$(CC) l(CFLAGS) -c $<

.b^.o:

$(GET) $(GFLAGS) $<
$(CC) $(CFLAGS) -c $<
rm $<

.o.exe:

$(GC) $(CFLAGS) +D $<

.c.exe:

$(CC) $(CFLAGS) +D $<

.c~.exe:

$(GET) $(GFLAGS) $<
$(CC) $(CFLAGS) +D $<
rm $<

This table may be reproduced, with the output appearing on the standard output, by
the following command:

make +p f=$null

Given all of the above capabilities, the description file for the print_setup program
can be reduced to the following:

# Description file for print setup program

OBJECTS = printsetup.o small.o normal.©

HEADERS =setup.h print.h

printsetup: $(OBJECTS)

cc $(OBJECTS)

print_setup.o smail.o: $(HEADERS)

Because normal.o is dependent only on its source file, it needn’t be mentioned as a
target anywhere in the description file. Its source file will be found by the use of
the suffix table and will be made (if necessary) using the transformation rules.

Utilities

[MAKE]

MAKE

Alternate Implied Source Directories

By default, MAKE expects that the source dependent be in the same directory as
the target. However, this is not always the case. It is sometimes useful to have the
source "scattered" across a number of directories and have MAKE search these
directories to find the source. The alternate directories are specified using the
pseudo-target .ALTJDIRS, as follows:

.ALTDXRS: ver2.0 verl.2 verl.l verl.O

Placing the above line in your makefile will cause MAKE to search the alternate
directories in specified order for an implicit source dependent after first searching
the directory of the target. This example will give you some ideas as to how
MAKE may be used for simple version control. (The current directory is the most
recent source. If the source isn’t here, start looking back at the earlier version
archives).

If you are working with C source in the above scenario, you must tell the CC
command where to place the object files it compiles (they default to the same

directory as the source). If you specify the following C compiler flag:

0=$(@D)

for example:

CFLAGS = 0=$(@D)

then when C source is compiled to object, it will automatically be placed in the
"target" objects directory (usually the current directory).

Recursive Makefiles

Another feature of MAKE is the ability to have make invoke itself. This is useful
if the description file is too complicated (or too large). If a command line contains
the sequence "$(MAKE) M anywhere, the line will be executed even if the -execute
flag is set. Since the -execute flag can be carried across invocations of MAKE via
the $(MAKEFLAGS) macro, the only command that will actually be executed is
the MAKE command itself. For testing purposes, make -e can be executed and
everything that would have been done will be printed, including output from lower
level invocations of MAKE.

An example of a command line invoking another level of MAKE is:

$(MAKE) $(MAKEFLAGS) f=makefile2

[MAKE]

Utilities

MAKE

It is also occasionally useful to have a target dependent on a file which is
maintained by a makefile in another directory. The usage of the d= option to
facilitate this is described in the section on Extensions to $*, $@ and $<.

See Also:

Utilities

[MAKE]

MKBIR - Make directory

mkdir directory [size]

size - Initial size of directory (default: 10 entries)

mkdir dirl

mkdir 3:/cmds/backup 20

MKDIR will create a directory with the given name. If a simple name is given, the
directory will be at the current directory level. If the name starts with a slash (/),
then the complete pathname from the root of the file system is specified. A drive
number followed by a colon (:) can precede the pathname which forces the
directory to be made on the given drive. Otherwise, the directory will be made on
the first drive it finds which matches the prefix. For instance, the second example
above will create a directory "/user" on drive 3. Without the "3:", the directory
would be created on the first drive searched, which is often a ramdisk.

Space is initially reserved for 10 files if no size is given. Note that directories, like
files, will grow so that this size parameter does not limit the size of a directory.
Directories can contain any number of files, but may become fragmented if the
initial size is not made large enough which often implies a speed penalty when-
opening files.

mkdir 2:/cmds 100

See Also:

DREL FREL RMDIR RM

[MKDIR]

Utilities

MORE - Display a file or stdin by pages

Syntax;

more [<stdin \ filename I x=filename]* [options]*
options: +numbers +raw -tab

Options:

filename - Name of file to print (default: keyboard)
x=filename - Name of index file that names files to browse
+numbers - Display line numbers

+raw - Don’t interpret escape sequences

-tab - Don’t expand tab characters

Description:

MORE is a file browser that uses the high speed terminal display routines to
display a file on the console. While the file is being viewed on the console, it is
also being stored in a large, dynamically allocated buffer. This buffer allows text
that has scrolled off the screen to be "rolled back" for later review. Note that only
the last 60K ( approximately ) of viewed text can be reverse scrolled.

After the first page of output has been displayed, various commands are available.
The most used of these commands would be those that cause the display of more
text to be started and stopped. This can be done a number of ways. The space bar
can be pressed to start and stop output, the XON / XOFF ( A S and A Q ) characters
can be used, the space bar, or the large plus key. Once the scrolling has been
stopped, a menu appears at the bottom of the screen to prompt for further
commands.

FI or - These keys can be pressed to display a help menu.

Left and Right cursor keys - These keys allow the text to be scrolled to the left and
right.

Up and Down cursor keys - These keys allow forward or reverse scrolling a line at
a time. New text from the file will be loaded and displayed if viewing past the end
of buffered text is attempted.

Utilities

[MORE]

Control Up and Down - Depressing the control key while typing the up or down
arrows will cause the text to jump up or down by four lines. This is intended to
mimic the action of the same keys in the QNX editor.

PgUp and PgDn keys - These keys allow viewing text in a forward or reverse
direction a page at a time. New text from the file will be loaded and displayed if
viewing past the end of buffered text is attempted.

Home - This key restarts the display at the top of the buffered file. If the amount of
text buffered has exceeded the buffer size, then the earliest text still in the buffer
will be used as the starting point for the display.

End - This key causes the text in the last page of the buffer to be displayed. Only if
the actual end of file has been reached, will the text at the end of the file be
displayed. If the end of file has not yet been reached, pressing the space bar will
cause output to resume at that point.

V - This key causes the currently displayed page to be redisplayed with line
numbers along the left column.

Digits 9 1 9 through 9 9 9 cause the text to be advanced by the corresponding number
of lines.

9 F 9 or 9 / 9 - MORE will prompt for a pattern to find within the buffered text. Once
the text has been found, the screen will be updated such that the located text
appears in the top line of the screen. Executing the find again will cause the next
pattern to be found. The pattern describes a template which the filename must fit.
Two special wildcard characters and ’?’ may be used in defining the pattern.

9 * 9 will match any run of characters (or none at all), whereas 9 ? 9 will match any
single character. In addition, any characters enclosed in square brackets ([ ])
indicate that any one of those characters will match. The escape ’V character can
be used to match the wildcard characters. A 99 character can be used as the first
character in the string to indicate that all names NOT matching the pattern are to
return a match condition.

9 r 9 - This key toggles "raw" mode on or off. MORE will by default attempt to
display escape sequences in a file with the appropriate display attributes. For
example, an Escape followed by a ’<’ character would turn BOLD on. See the
operating system manual for other escape sequences. With raw mode turned on,
the actual escape characters will be displayed rather than interpreted into the
appropriate visual modes.

Tab or 9 t 9 - This key toggles the display of tab characters in the viewed text.

[MORE]

Utilities

Escape key, V or ’x’ - These keys exit the file browser.

Enter key or ’q’ - These keys advance the file browser to the next named file if
multiple files were specified. If only one file was specified, this key exits the
browser.

The ’z’ key flips the screen through the various screen resolutions. For example, on
an system equipped with an EGA display card and the appropriate graphics driver
mounted, the zoom command will toggle the screen between 80 by 25 line mode
and 80 by 43 line mode. When an exit from the MORE command is. performed, the
original display mode is automatically reselected.

Note: Browsing multiple files from a single invocation of MORE causes the

displayed line numbers to count from one for the first file and continue from that
point for each successive file.

See Also:

CAT

Utilities

[MORE]

MOUNT - Mount a new disk drive or new memory

Syntax:

mount, disk drive[d~driver num\ [load file] [h-v]

[s =size] or [pa -osjype]

[h =heads t-tracks n-sectors! track]

[p=physical_drive] [c=ctl_addr\ [i ^interrupt]

[u=user_data] [w=write_precomp_cyl]

[+large_xtnts] [-large_xtnts]
mount cache d-drive_number s=size[k]
mount xcache s=size[k]
mount bmcache d =drive_number
mount ramdisk drive [loadjile] [s=size] [-v] [+v]
mount remdisk drive m=node_number d-drivejmmber
mount console [device jiumber] newjiame
mourn; lib load Jile [+v]
mount file loadjile [+v]
mount debug [load Jile] [+v]
mount mem m-segment s=size
mount float
mount

Options:

load Jile - Specifies the name of a disk driver load file which can be used

to control this drive. If none is specified, the floppy drivers
will be used. In the case of MOUNT DEBUG, loadjile is
the name of the debugger to use which defaults to
"/cmds/sys.debug". If MOUNT FILE or MOUNT LIB is
used, then loadjile is the name of the file to load,
s =size - Specify the storage capacity of the disk if different from the

default value specified in the driver load file. This option is a
short form useful when mounting special floppy diskettes. It
is also used when mounting special memory. Always use the
h=, t= and n= options (and never s=) for hard disks. The
letters "k", "K", "m", M", Y or ’T may follow the size to
indicate sizes in Kbytes, Megabytes or Tracks. Otherwise,
the number refers to the number of 512 byte disk blocks (or
16 byte memory blocks for MOUNT MEM). The postfix M
should be avoided since it provides only a very course
resolution of size. The postfix T refers to the number of

Utilities

[MOUNT]

MOUNT

tracks under one head. It is often referred to as cylinders as
well.

m-segment - Starting segment of new memory being added, (top 16 bits
of 20 bit memory address). This will not work in protected
mode.

p -drive - Use this physical drive rather than drive 1.

pa =os_type - Use the partition information to determine the correct offset

and size to mount the disk. You may still need to specify the
correct t=, h= and n=. The os_type may be the characters
qnx, dos or a number between 1 and 255. The characters
qnx are the same as the number 7 and dos is the same as the
number 1. To use this option you must have set up a partition
using the FDISK command.

c =ctl_addr - I/O control address used by driver. This option will rarely be

used since this information is in the supplied driver,
i ^interrupt - Interrupt used by driver. This option will rarely be used since

this information is in the supplied driver.

-verbose - Don’t display any messages.

+verbose - Display extra information about where the driver or file is
mounted.

u=user_data - Internal use.

+large_xtents - used with QNX versions < 2.06
-large__xtents - used with QNX versions < 2.06
w -writejprecomp_cryl

- used as options to specify your own user data space when
writing a disk driver.

Examples:

mount disk 2t=80 h=2 n=8 - Mount drive 2 as a -640K floppy,

mount disk 2 s=640k - Also Mount drive 2 as a 640K floppy

mount disk 3 /drivers/disk.xt pa=qnx

- Mount drive 3 as a hard disk using the
driver found in the file "/drivers/disk.xt".
Mount the QNX partition.

mount ramdisk 5 s=128k - Mount drive 5 as a high speed memory

disk with 128Kbytes of storage (data is
stored in RAM instead of on a disk).
(Remember to DINIT the ramdisk before
using)

mount mem m=D000 s=128k - Add 128K of memory starting at hex

address DQOO.

mount debug - Load the system debugger into memory,

mount console $con2 - Mount another console

mount xcache - Mount a 2k extent cache (default)

mount cache d=3 s=48k - Mount a 48k cache on disk 3

[MOUNT]

Utilities

MOUNT

mount bmcache d=3 - Mount a bitmap cache on disk 3

mount lib /config/qdb.slib - Mount a shared library

mount float - Mount a floating point library

mount - Query mounted disks and devices

Description;

MOUNT allows the user to add new disk drives and custom disk drivers into the
system. In addition, memory which is not normally recognized when the system
boots may be included. The MOUNT command may also be used to load the
system debugger into memory, or to load any core file into memory.

If MOUNT is executed without any arguments it will print out what disks are
mounted in the system, all devices which are present, and any mounted libraries.

When QNX boots for the first time, it assumes that the setting of the DIP switches
within the PC correctly indicate how many floppy drives are connected to the
system, and how much memory is installed. All floppies are initially assumed to be
the same size as drive 1 unless you are on an AT, in which case the setup informa¬
tion in the CMOS ram is used. MOUNT can be used to change the ’’sizes" of the
remaining disk drives if they differ. As in the first and second example, the number
of disk blocks which can be stored on a particular drive can be changed. Only
users which have a non-standard disk drive need to remount their floppy drives.

In the case of a floppy, MOUNT provides two pieces of information,

1. The physical characteristics of the floppy drive. This consists of two
parameters, the number of tracks (40 or 80) and the number of heads (1 or 2).
The number of sectors/track is a function of the floppy diskette, NOT the
drive.

2. The default diskette format to be assumed for NON-QNX diskettes and QNX
diskettes formatted with early versions of the FDFORMAT command (QNX
1 . 1 ).

The FDFORMAT command places a table in block one of the diskette which
describes how the diskette was physically formatted. This information will always
override that specified by the MOUNT command. In the case where a drive is
mounted with 80 tracks and a diskette with 40 tracks is inserted (which contains an
override table) the system will perform double stepping to correctly read the
diskette.

Disk drives other than floppy disks require that a special driver be written to
handle them. The MOUNT command can be used to include these drivers into the
operating system. Special disk drivers are normally found on the boot disk under
the directory /config.

Utilities

[MOUNT]

MOUNT

The MOUNT command allows a user to create up to 15 logical disks. Only the
first 8 may be real physical disks. The others may be REMOTE or adopted disks.
For example, the filename "3:/tmp/test" is found on LOGICAL drive 2.

A hard disk can be partitioned into several logical volumes. The first logical
volume on the hard disk must be mounted first, specifying the name of a disk
driver file. Subsequent logical volumes on that physical disk can then be mounted
by specifying that the same driver is to be used (d=). The following will mount a
QNX and a DOS partition. The DOS partition would be accessed by a QNX-DOS
file system task (DFS).

mount disk 3 /drivers/disk.xt pa=qnx
mount disk 4 d=3 pa=dos

If a driver is capable of supporting more than one physical drive, then the p= op¬
tion can be used to force a particular physical drive to be used. For convenience,
the "MOUNT DISK" form of the command with no driver specified will use the
floppy driver, implicitly using the same physical drive as logical drive. Thus
"mount disk 2" will mount a logical disk 2 on physical floppy drive 2.

The mount mem form of the command is useful in systems where non-standard
memory cards are being used which may require some initialization before being
included into the system. In systems with large amounts of memory, the system
may take a long time to power-up due to the automatic memory check which is
performed by the firmware. Some people prefer to set the DIP switches to indicate
some smaller amount of memory which reduces the time required for power-up.
The MOUNT command can then be used to install the extra memory into the
system. However, it is recommended that if this practice is followed, regular
memory diagnostics should be performed to safeguard against memory failure. On
8088 based PCs or XTs, it can be useful to install an extra 128K of ram above the
video card (at D000) and an additional 64K just below the video card (at A000)
for a total of 832K (640K + 128K + 64K). Many PCs have this RAM already
installed on the motherboard, just waiting to be used. The commands

mount mem m=d000 s=128k

mount mem m=a000 s=64k

will "mount" this memory into QNX, ready for use by tasks or ramdisk.

The mount debug form of the command is used to load the system debugger into
memory. The name of a different debugger file may be given as an option.
Memory will be allocated for the debugger which will remain resident in memory.

[MOUNT]

Utilities

MOUNT

The mount file and mount lib form of the command are provided to allow user

compiled and linked programs to be loaded into a block of memory which is
allocated by the operating system. How the file is mounted depends on the first
byte of the linked loadfile. The LINKER will by default create loadfiles with a first
byte equal to 1. This byte can be changed with the PATCH utility. MOUNT
interprets this byte as follows:

1 : Common Code and Data (invalid in ATP) 2 : Not used 3 i Data Only 4 :
Code Only 5 : Common Code and Data (CS:0000 = DS) 6 : Split Code and Data
(CS:0000 = DS)

Type 4 is recommended for mounted libraries consisting of pure code (only seg 1
used in the assembler). Type 6 is recommended for libraries requiring local data
(MOUNT will put the data segment to use in byte 0000 of the code segment). The
+verbose option causes MOUNT to display the memory segments it has allocated
for loading.

Mounting a cache on a disk will usually speed up accesses to that media. A good
size for a cache is 48K. Mounting an xcache will cause the file system to cache the
linkage information which connects the extents within files. As a rule of thumb,
each xcache entry requires 16 bytes. Thus, only a few Kbytes of xcache can store
many extent headers. The FILES command will display how many extents each
file has, allowing you to judge how large an xcache might be useful. Xcache can
significantly increase performance for large data base files.

Normally the MOUNT command will be used in system initialization, and may be
conveniently included into the file 'Vconfig/sys.mit” which is automatically
executed when QNX is booted.

Only SUPER users can use the MOUNT command with options.

See Also:

FDFORMAT SEARCH

FDISK SH

NACC STTY

PATCH

Utilities

[MOUNT]

MSORT - Merge sort utility

msort [file ] [options]*

Options:

i=field[field]*

l=maxjines

+descending

+replace

r=output_file
p= directory

•verbose

Define sort fields

Maximum number of lines to buffer in

memory

Sort in descending order
Replace file with sorted output
Place sorted output in output file
Pathname of a directory where temporary
files are to be placed. The default is the
current directory.

Suppress sort and merge phase messages

Where:

field is field_offset. field_width

left column is 0

Examples:

msort inventory f=0.10,10.4 +r

msort data f=10.5,4.3 r=sort_data p=/tmp

Description:

MSORT will sort files based on fixed fields in fixed records. Each record (line) is
terminated by a record separator (hex IE, *\n’ in C programs) and all records
MUST be the same size.

The sort is accomplished in two phases. The sort phase reads and sorts the input
file in large chunks, appending the sorted chunks into two temporary files. The
merge phase merges die sorted chunks from the two files into larger chunks in two
other files. This is repeated until only one chunk remains. Unless -verbose is
specified a dot will be printed as each chunk is processed in each phase.

Utilities

[MSORT]

MS0ET

Sorting is based on the ASCII values of the characters in the file. The order and
definition of the fields is specified with the f= option. The offset is based at zero
which is the left hand column. The width is based at one which will sort a single
character.

The +r option causes the output of the sort to replace the contents of the original
file. The output may be redirected to another file using the r= option. If neither the
+r nor r= ootions are used, the output will go to the standard output which defaults
to the screen.

The sorted output will normally be in ascending order. This can be reversed to
descending order by specifying +d.

The 1= option will limit the number of records MSORT will attempt to buffer in
memory. It can be used to keep MSORT small at the price of efficiency. If not
specified, MSORT will attempt to buffer the maximum number of records which
will result in a data segment of close to 64K.

During the sort and merge phase, MSORT will create temporary files with the
names

MSORT.n.nid.tid
where: n is 0,1, 2 or 3

nid is the nodeid of machine MSORT is running on
tid is the taskid of MSORT

These files will be removed if MSORT terminates normally. Users with a large
ramdisk may wish to place the temporary files there to increase performance. This
may be accomplished using the p= option.

See Also:

SORT

[MSORT]

Utilities

- Move files

mv sourceJile destination Jile
OR

mv file* directory

mv *.c /c_source - Move all c files to the directory

/c_source.

mv test.c good.c - Rename the file test.c to good.c

The first form of MV will move a source file to the destination file. This form of
MV allows the file to be renamed as it is moved. If the directory of the destination
file is the same as directory of the source file, the file is simply renamed in place.

The second form of MV will move multiple files to the specified directory. This
provides a convenient method of moving multiple files in one simple operation.
The SHELL special characters *, ?, and [...] are useful for selecting the set of files
to be copied. If the error

LINE TOO LONG

is displayed, you will have to restrict the number of files moved and issue one or
more commands.

mv *.[co] dir --> mv *.c dir

mv *oO dir

The utility WS is also useful for getting around this problem. For example:
ws "mv @ dir" p=*.[eo]

Utilities

[MV]

The following two commands achieve the same effect using the two forms of MV:

mv /test/file /release/file - destination is a file

mv /test/file /release - destination is a directory

For all forms of MV, if the directory the source file is in is the same as the final
directory, then MV acts only to rename the file. If the destination directory is on
another device (e.g. moving across a network or from floppy to hard disk), MV
acts by copying the contents of the source file, then deleting it. If the directory is
on the same device, the file is logically moved, with no data actually being copied.

See Also:

[MV]

Utilities

NACC - Set network access to disks, devices and CPU

Syntax:

nacc [cpu] [%device\* [drive]* [+read] [+write]
[-read] [-write]

Options:

cpu » Control access to CPU.
device - Control access to $device.
drive - Control access to disk drive.

-{-read - Allow read access.

-read - Disallow read access.

+write - Allow write access.

-write - Disallow write access.

Examples:

nacc cpu -{-write

nacc 1 $lpt $mdm -w -r
nacc 2 +read

Description:

NACC may be used to control network access to your local disks, devices and
CPU. If you remove both read and write, then network access will be denied. The
NACC command only affects network access. It has no effect on requests which
originate from the local machine.

Allowing CPU write access allows non super-users to execute tasks remotely on
your machine. CPU read access is not currently defined. The default at boot time
is to disallow everything.

Network access permissions do not apply to super-users (group 255).

- Allow non-superusers on other
nodes to execute commands on
this node.

- Remove network access from
drive 1, $lpt and $mdm.

- Allow network access to drive 2.

Utilities

[NACC]

NACC

If a non super-user tries to execute a task on a remote node, he must have
previously allowed read / write access to his console. This is because his remote
task will try to access his console from across the network. For example, if the
command:

[4] mount

is executed from node 2, the user on node 2 must first have executed the command
nacc $con +r +w

to grant the mount command running on node 4 permission to display its output on
the user’s console from across the network.

See Also:

ALIVE

MOUNT

STTY

[NACC]

Utilities

NET - Query machines on the network

net [node_id] options*

node_id

-clear

+horizontal
-{-vertical
+repeat
p -priority
s-nodejd
Q=node id

Only display information on this node.
Don’t clear the screen first.

Horizontal display option.

Vertical display option.

Repeat until a key is typed.

Priority to run net (used with repeat).
Start display at the indicated node.

End display at the indicated node.

net
net 3

net s=6 e=l 5 +v

net -c +r

NET may be used to examine the resources of machines connected together in the
local area network. NET may only be used with networking versions of QNX.

In the full screen display modes (+h or +v option), many nodes are displayed and,
if 4 -repeat option is specified, continuously updated on the screen. Pressing any
key will cause NET to exit from repeat mode.

The s= option may be used to start the display at a particular node.

Note that NET will use the TCAP database to define the terminal characteristics

for full screen mode. If the terminal has not been defined, NET will display:

Can’t find terminal type (see TCAP utility).

Utilities

[NET]

NIT

You must then define or set the terminal type using the TCAP command. Not using
the +h or +v option removes the need for the TCAP database.

NET displays the system resources which are free (out of total available) for each
node in the network. Free memory and available tasks virtual circuits are displayed
in all display modes.

The default, non full-screen mode of NET will also display the QNX version
number, free memory, CPU speed, number of ttys on that node, number of
signaling ports, maximum number of open files and the CPU flags for that machine
(same definition as for the TSK command).

See Also:

TSK

WHO

[NET]

Utilities

NETBOOT - Service boot requests from the network

Syntax:

netboot [options]* &

+broadcast
+verbose
f -bootjile
T-retries
s -slow_down

Examples:

Broadcast boot packets.

Print boot requests on the screen.

Default boot file.

Number of retries on a network error.

Pause between dumping boot packets on the network.

netboot f=os.2.10pcat &
netboot +v &
netboot +b s=3 &

Description:

NETBOOT accepts boot requests from machines which wish to boot over the
network. It must be running as a background task on the boot machine before
another (booting) machine can boot. Upon receiving boot requests it supplies boot
records to the requesting machines.

QNX operating system boot image files are kept under the directory /netboot. To
prevent confusion, the names of the files in this directory have been chosen to
indicate the operating system they represent.

os. if.ff r type

where n.n
r

type

is the version number (eg: 2.1)
is the release number (single digit 0 .. 9)
is a hardware machine type
peat - IBM PC, AT, PS/2 or compatible
atp - IBM AT, PS/2 or compatible railing in protected mode
hv - HP Yectra (before the ES or GR series)
hvp - HP Yectra running in protected mode
(before the ES or GR series)

Utilities

[NETBOOT]

NETBOOT

The following are typical boot files.

os.2„10pcat - PC or AT, real mode, release 0.

os.2.16atp - AT, protected mode, release 0.

The name of the file to boot from is set in a non-volatile ram on your network
card. If the boot file name in the card is left blank NETBOOT will default to the
file specified with the f -bootjile option.

Unless requested, NETBOOT will only boot one machine at a time. If you select
the -{-broadcast option, NETBOOT will send boot requests to all machines in the
network. This allows more than one requesting machine to boot in parallel. There
is a danger in using broadcast. It will place a load on machines which are already
running and it is possible for a very fast server to overrun the network input buffer
of a slow machine which is trying to boot. To avoid this you may have to to slow
down NETBOOT with the §=slow_down option. You will have to experiment but
we recommend numbers between 1 and 100. The -{-broadcast option should be
avoided unless you really have a need for it.

You will probably wish to place this command near the end of the system

initialization file for the machine acting as the boot server.

[NETBOOT]

Utilities

NETSIZE - Configure Network Size

Syntax:

netsize [f=floppy] [h ^harddisk]

f -floppy - Floppy disk drive to read from. Default = 1.

Ji -harddisk - Hard disk drive to write to. Default = 3.

netsize

netsize f=2

netsize f=[2]l h=[5]3

netsize ti=[2]3

Description:

NETSIZE is used to configure the size of the network. It does this by prompting
the user to insert each Boot disk and Network Expansion disk purchased into the
indicated floppy drive. For each floppy disk inserted, NETSIZE copies the network
size information to the indicated hard disk. The defaults are to read from floppy
disk 1 and to write to hard disk 3, but these can be otherwise specified with the
f -floppy and b-harddisk options. If the local disk drive is not compatible with the
media (for example, 3.5" and 5.25" disks ), a network remote floppy drive can be
specified as:

$ netsize f=[3]l

This causes NETSIZE to read from floppy drive 1 on node 3 and to write the
network size information to the hard disk 3 on the local machine. NETSIZE should
be run such that it writes to the 3 dnetdisks directory on each hard disk in the
network that a machine will be booting from.

Every QNX Boot disk is worth 1 node on the network and Network Expansion
disks are worth various numbers of nodes. NETSIZE makes it possible to to
combine these various disks into a larger network license. If you currently have a
10 node network, and wish to add 5 more nodes, all you need to do is to purchase 5

[NETSIZE]

Utilities

NETSIZE

more network cards and a network expansion disk which is good for 5 nodes. Re¬
running the NETSIZE utility, and inserting the new network expansion disk when
prompted will automatically upgrade your hard disk to reflect the new network
size. Rebooting QNX from this hard disk will cause the new network size to take
effect.

The BACKUP and TBACKUP utilities will copy the files stored within the
/netdisks directory but the copied files are not useful for network configuration.
You should specify that TBACKUP and BACKUP not copy the contents of the
Inetdisks directory ( at least for the restore ). If you are restoring from a backup to a
hard disk, you will need to re-run NETSIZE with your various disks to have the
node boot from its own hard disk and also participate on the network. This also
protects the network from network workstations booting from floppy disk and
accessing the network, since only a hard disk boot from a disk where NETSIZE
has been run can participate on the network.

For a first time installation, the 3:Inetdisks directory is automatically created by the
INSTALL utility before it attempts to run the NETSIZE utility. If you are
manually running the NETSIZE utility it is important that the 3:1 netdisks directory
be manually created first. Manually creating this directory helps to ensure that the

local Inetdisks directory will be updated, and not another one on the network.

If at any time things appear to not work, ZAP the 3:Inetdisks directory on the hard
disk, use MKDIR to create a new 3:1 netdisks directory and re-run NETSIZE. Also
run CHKFSYS to reclaim the disk space lost by using ZAP.

See Also:

Network Installation section of the QNX Manual

Utilities

[NETSIZE]

NETSTATS - Display network statistics

Syntax:

nets tats [options]*

Options:

m=node - The node whose statistics you wish to query. The default
is your local node.

+clear - Clear the statistics after returning their current values.

+report - Generate report style output

+all_nodes - Display statistics of all nodes on the network.

+monitor - Enables monitering of network,
o -offset - Offset in minutes for displaying logged information.

dl=dd-mon-yy - Start date for displaying logged information.
62=dd-mon-yy - End date for displaying logged information.
tt-hh:mm:ss - Start time for displaying logged information.
t2 =hh:mm:ss - End time for displaying logged information,
d -monitor__depth

- Monitor sample size. Default is 1000 samples,
m -monitorjnask

- Mask of bits to monitor (hex).

Description:

NETSTATS will print out network statistics on a node in the network. These
values can be used to detect network errors and network load experienced by a
node. Unless you use the -f dear option, the counters used for the statistics will
continue to increase in size over time. You must be a super-user to clear the
counters.

The following information will be displayed:

Min Packet Queue: 97

Each outgoing message is placed in an outgoing packet queue. Messages will be
lost if this queue goes to zero. This field displays the minimum number of free
entries the queue has experienced.

Packet Queue Overrues: 0

Each time the packet queue goes to zero and a message is lost this number is
incremented. This number should remain at zero.

Utilities

[NETSTATS]

NETSTATS

Network Rx Packets: 24,795

The number of packets transmitted by this node.

Network Tx Packets: 22,257

The number of packets received by this node.

Reconfigurations : 32

How many times the physical network has reconfigured since your node was
booted. This value will increase every time a new node enters the network, and

should not be considered an error. If this value increases when no node enters or
leaves the network, it could indicate faulty networking hardware or noise on the
cables (possibly caused by passive hubs).

Network Tx Errors: 7

This value indicates the number of packets which were corrupted while
transmitting, or which were sent to non-existent node-ids. Non-zero values should
not necessarily be considered an error, since QNX will retry several times. Every
network reconfiguration COULD cause this value to increase. A poller will cause
this value to increase every time a non-existent node is polled.

Network Tx Timeouts: #

This value indicates the number of times packets were unable to be sent to another
node which has a working network card, but whose software is not responding.

This should be considered an error unless a poller is running on your machine.

Network Tx Aborts: 1

This value indicates the number of times QNX gave up when trying to transmit a
packet. This should be considered an error unless the poller is running on your
node.

Network Rx Errors: 0

This indicates how many bad packets were received. This value should always be
zero.

Network Rx Duplicates: 0

This value indicates how many duplicate packets were received and rejected. There
is a possibility of receiving a duplicate packet whenever a new node enters the
network, or whenever the network is noisy. Non-zero values are not necessarily an
error, but could indicate faulty hardware if excessive.

Network Monitor Mode

The Network Monitor Mode can be very useful for examining and diagnosing
your network. It will keep track of a series of events related to your node in rela-

Utilities

[NETSTATS]

NETSTATS

tion to the rest of the network. Here is a list of the events which are logged:
Event Mask Bit

TXJRetry

TXFailed

RXJDuplicate

RXInvalid

Reconfig

RX_Failed

Timeout

Netbootbegin

Netbootend

NetjolI_fail

Netj>oll_dowii

Net_poll_up

OOOlh

0002h

0004h

0008b

0010b

0020b

0040b

0080b

0100b

0200b

0400b

0800b

Each entry is time stamped. To enable logging, enter the following at the command
line (or put in your sys.init.nn file ):

netstats +monitor

Then at any time in the future, you may query the current in memory log of events
by entering:

netstats

The m~monitor_mask option cap be used to select (mask) which events you wish
to monitor/log. See the above table for the mask bit definitions.

The following options can be used for displaying the logged information:

o-offset

M=dd-mon-yy
d2=dd-mon-yy
tt=hh:mm:ss
t2 =hh:mm:ss

See Also:

NETTEST

Utilities

[NETSTATS]

NIETTEST

NETTEST - Check data transmission between two nodes

Syntax:

nettest node [min [max]]

Options:

node - The destination node to test. You local node is
always the source.

min - The minimum number of 16 bit words to send. Default 1.

max - The maximum number of 16 bit words to send. Default 500.

NETTEST will send data between your local node and a specified destination node
checking the data at both ends. To accomplish this, NETTEST creates a remote
task on the destination node. If you do not specify the minimum and maximum
number of 16 bit words to send they default to 1 and 500. Messages of random
size between these two values are generated for the test.

NETTEST should run without errors for millions of messages. Errors can occur
when cables are disconnected from machines connected to a passive hub.

See Also:

NETSTATS

Utilities

[NETTEST]

ONTTY - Create task on another tty

Syntax:

ontty ttynum command-line
ontty ttyname command-line.

• This is a local shell command •

Description:

The ONTTY command executes the indicated command on the indicated tty. The
command is detached from your terminal and inherits your accounting information
and current directory. After mounting a console you may wish to create a SHELL
or LOGIN on that console.

mount console $con2
ontty $con2 sh
OR

ontty $con2 login

If this command is combined with the syntax of remote task creation, then the
remote node should precede the ONTTY. You may also specify the node number
as part of the device name.

[4] ontty $con2 ed file

ontty [4]$con2 ed file

These will create the editor on $con2 of node 4. The editor will attempt to read the
indicated file using the search order on node 4.

If you know the device number you may directly reference it.

ontty 3 login

See Also:

MOUNT

[ONTTY]

Utilities

OSCONFIG - Change operating system parameters

Syntax:

osconfig filename [+l-dos]*

Options:

filename - The name of the configuration file.

+dos - Enable the reserving of base memory for DOS
=dos - Disable the reserving of base memory for DOS

Examples:

osconfig 3:/config/sysxfg

osconfig 3:/config/sysxfg.4 +dos

Description:

OSCONFIG allows you to specify a configuration file which lets you change some
of the operating system defaults such as the number of open files supported.

An operating system may boot from 1 of three sources.

L Floppy
2. Hard Disk

3* Network

When booting over the network, the NETBOOT command attempts to open a file

by the name

/config/sysxfg.uFi

where nn is replaced by the node number of the booting machine. If successful,
the operating system will use the parameters in this file, otherwise it will use it’s
defaults.

Booting from disk is a little different. The configuration file must be explictly
bound into the operating system using the BOOT command. This is specified as a
c=3 :/conf!g/sys.cfg. #t» option to the BOOT command. You may select any file
name, however, we suggest you use the same convention as that used by
NETBOOT. On a single machine you may omit the ".nn".

Utilities

[OSCONFIG]

OSCONFIG

/config/sys.cfg - Single machine.

/config/sys.cfg.nn - Network machine.

The sys.cfg file is created and maintained by the OSCONFIG command. For
example

osconftg 3:/conflg/sys.cfg

would create a configuration file for a single non-networked machine, it is active

for network booting but does not become active for disk booting until you use the
BOOT command to set it.

NOTE . 0 When booting from hard disk you should not remove the config file
name after you have selected it with the BOOT command. You may copy a new
file on top of it but NEVER remove it (FREE, RM,...) and then create a new one

even if it has the same name. The BOOT command saves away the absolute
starting block numbers of each of these files which will change once the file is
removed. When booting over the network, the NETBOOT command opens the
file through regular means and this is not a concern.

See Also:

BOOT

NETBOOT

[OSCONFIG]

Utilities

P - Print file contents on terminal

Syntax:

p [file] [+raw]

Options:

file - Name of file to print (default: keyboard)

+raw - Don’t expand control characters

P joe

p picture +r

p ilici

Description:

The P command prints the contents of a file. Output is sent to the standard output.
If no input file is specified, it will default to the standard input. Any unprintable
characters will be expanded into \hh where hh is the hex value of that character.
This expansion can be turned off by specifying the + r option.

See Also:

COPY

. DUMP

Utilities

[P]

PACK

PACK - Pack a file to reduce its size

Syntax:

pack file* [-remove] [-verbose] [-time]
or

pack <infile >outfile [-verbose]

Options:

-remove - Suppress the removal of input files.

-verbose - Suppress status messages.

-time - Retain original file time. Set to current time by default.

pack *.c - Pack all C files

in current directory

unpack *.z - Unpack all packed files

in current directory

pack ctext >packed - Pack file "text" and put

packed file in ’’packed"

PACK compresses files into a more compact form. Any file can be packed, but
program source files and text files benefit the most, typically shrinking by 35%.
Files containing only a limited character set, such as dictionary files, may shrink as
much as 48%. Packed files look like gibberish and must be unpacked before they
can be used.

The unpacker, UNPACK, expands packed files into exact duplicates of the
original.

As each file is packed, a of message of the form:

Analyzing "filename” ... packing... size = 70% of original
will be displayed. This can be suppressed by specifying the -verbose option.

Utilities

[PACK]

PACK

When the first form of PACK is used each file will be replaced by a file with the

same name and a .z appended. A filename may not exceed 16 characters so you

should limit the name length of input files to 14 characters. The input file will by

default be removed. You can suppress the removal by specifying the -remove
option.

When the second form of PACK is used it will read from the standard input and

write to the standard output. In this case the input file will never be removed and
you have control over the name of the output file.

The data in the file is treated at the byte level rather than the word level, and can
contain absolutely anything. The compression is in two stages: first repeated byte
values are compressed and then a Huffman code is dynamically generated to match
the properties of each particular file. This requires two passes over the source data.

The decoding table is included in the packed file, so packing short files can
actually lengthen diem. Fixed decoding tables are not used because English and
various computer languages vary greatly as to upper and lower case proportions
and use of special characters. Much of the savings comes from not assigning codes
to unused byte values.

See Also:

UNPACK

[PACK]

Utilities

PARK

P ARK - Park the heads of a hard disk

Syntax:

park drive

drive - QNX drive number of disk to park.

park 3 - Park heads of dive 3.

PARK is called to park the heads of a hard disk prior to turning power off the
machine. A disk with parked heads will have a much smaller chance of being
damaged should power fail, or if the unit is being moved.

The PARK utility will determine the actual size of the hard disk and attempt to
move the heads to the inner-most track of the disk.

IMPORTANT: The PARK utility remounts the hard disk to position the heads, so
should only be called when the system is idle. No other users or programs should
have any open files when PARK is issued.

[PARK]

Utilities

PASSON -Turn on password protection

Syntax:

passon

• This is a local shell command •

Description:

The PASSON command will cause the LOGIN command to look for the file
"/config/pass" and enforce password protection on login. If this file does not exist
you will be unable to login. Systems that have booted from a QNX network will
have passwords on by default.

Once passwords are enabled, they cannot be turned off.

Utilities

[PASSON]

Syntax:

patch file [options]*

Options:

o =offset
b -byte

s=stack_size -
+change_user -

-changejiser -
+high__load

-highjoad

+privileged

-privileged
+remote_ok -

-remote_ok

+shared

-shared

+8087

-8087

Examples:

patch program
patch core +p
patch myjprog +s
patch data o=2 b=

Specify offset in file to patch (hex).

Specify new byte at this offset (hex).

Set the stack size for an executable program.

Make command ran with effective user
of user which owns the file.

Remove change jowner flag.

Force command to be loaded into high
memory.

Remove highjoad flag.

Make command privileged.

Remove privileged flag.

Allow command to be executed on a

remote node.

Don’t allow command to be executed
on a remote node.

Make command sharable.

Remove shared flag.

Indicate that command needs an 8087.
Pretend that the command doesn’t
need an 8087.

Display the current patch status of the file.

Make the file "core" privileged.

Make "my_prog" sharable.

Patch the 3rd byte of the file "data" replacing it with the byte
2a hex.

[PATCH]

Utilities

PATCH

Description:

PATCH can be used to modify the attributes of an executable file or it can be used

to patch any byte in the file.

Setting the change_user flag will cause the command to assume an effective user
number which is the same as the file. If the file is owned by the super-user, then

the command will ran with super user privileges regardless of who executes it. For

example,

patch /cmds/date +c
will allow anyone to set the date.

Setting the tiighjoad flag causes the code segment to be allocated at the top of
memory. Normally code and data are allocated at the low end of memory. This
flag may be set on tasks which remain in memory for long periods of time (such as

CLOCK). By keeping these long lived code segments high in memory, memory

fragmentation problems are reduced.

Setting the privileged flag allows the privileged system functions to be used. Only
files which are created by the super-user AND which have been made privileged
will be allowed access to these functions. The absolute disk block I/O functions of

DISK JRE AD JB LK and DISK_WRITE_BLK require that the task be privileged.

Setting the remote ok flag allows a command to be executed on a remote node
even if remote task creation has be disallowed on that node. This allows informa¬
tion programs to be run remotely by a non super-user.

Setting the shared flag allows multiple instances of this command to be created
without going to the disk. Instead, the code is shared and any constant data is
copied form die data segment of an existing task. Each task will still have its own
data segment. For example, the SHELL and the EDITOR have been made
sharable. The program must not have have any initialized global variables.

Setting the +8087 flag will cause the system to refuse execution if there is NOT an

8087 installed in the system. Any programs which contain 8087 opcodes will.
automatically cause this flag to be set. However, in some instances, the majority of
a program may never use the 8087 and can still be used on systems which do not
have an 8087 so long as these opcodes are avoided. For these programs, the -8087
option allows the USES__8087 flag in the load file to be turned off. It is the user’s
responsibility to assure that these opcodes are never used on machines which do
not have an 8087, as the hardware will hang forever!

Utilities

[PATCH]

PATCH

See Also:

DUMP

SPATCH

[PATCH]

Utilities

P ATH - Change command search path

Syntax:

path searchpath

• This is a local shell command •

Description:

Each time a command which does not start with a slash is executed by the shell, a
list of directories is searched for an executable file. The default is 7cmds/ M
followed by the current directory. This may be changed using the PATH
command followed by a list of directories surrounded by exclamation marks. For
example, to search the current directory followed by "/cmds" followed bv

i U£)vi/ WiliUo

path ! !/cmds/!/user/cmds/!
and to return to the default
path !/cmds/n OR path
You may print your current search path with
path ?

Utilities

[PATH]

Syntax:

poll [-{-verbose] [-verbose] [\-logJile]

[p -polljperiod ] [r -retries] [s=slow poll_period ]

poll &
poll +v

poll l=poll.log
poll p=20 &

Run the poller.

Run poller with full screen display.
Create a log of status changes.

Poll nodes every 20 ticks (1 second).

The POLLER is responsible for ensuring that resources are reclaimed when a node
goes down. It should be run on a node which is always UP, probably the node
which is used to download other nodes, or acts as a fileserver to other nodes.

The POLLER scans all nodes which are alive and ensures that they are capable of
receiving communications. If a node fails to respond to the poller in a reasonable
amount of time, it is marked as DOWN and all other nodes are informed. This has
the effect of releasing any resources which this node may have been used
anywhere on the network.

The POLLER will also poll one DOWN node for every complete cycle of polling
UP nodes. This is called the slow poll and may be eliminated by specifying M s=0".
The slow poll will discover nodes which have recently booted, but at a much
slower rate than it finds nodes which have crashed. The s= option can also be used
to reduce the rate of slow polls if discovering newly booted nodes is not critical.

The POLLER will poll a node every 5 ticks which amounts to 4 polls per second.
The p= option can be used to alter this rate, but the default rate provides good
results for most network configurations. The POLLER decides that a node has
crashed when it has attempted to poll the same node 3 times without receiving a
response. The number of retries can be changed with the r= option, but 3 retries
should be sufficient since QNX will always reply to poll messages immediately if
it is UP, and the network should never be so busy that a poll message can’t be sent
and a reply received within 1 second.

[POLL]

Utilities

POLL

The operating system will not initiate any communications with another node
unless it thinks that node is UP.

BUSY status is useful to temporarily remove a node from the network without
releasing any resources on other nodes. This might be done on a node before using
the debugger to prevent the POLLER from flagging the node as down.

alive +b

When the debugging session has ended, the alive command can again be issued to
tell the poller that the node is now UP and ready to receive communications from
other nodes.

alive -Hip

When a node is first booted, it is usually a good idea to inform the poller that the
node is now up rather than waiting for die slow poll to discover the fact. The poller
will then broadcast this information to all other nodes in the network. To achieve
this, include the ALIVE command in the "/config/sys.init" file.

alive +n

NOTE: For proper operation, only ONE poller should be running on a QNX
Network.

See Also:

ALIVE CLRHOUSE KILL_VCS NACC

Utilities

[POLL]

PMI - Set priority

Syntax:

pri number
pri -{■number

pri -number

• This is a local shell command •

Description:

Set the priority of commands executed by the shell. A V increases it while a
decreases it. If no argument is given the priority is set to the default of eight. The
priority must lie within 4 and 15 with 4 being the highest priority. Smaller values
have higher priority. The command.

pri -1

will ADD one to your priority number which will cause the command to run at
LOWER priority. The priority number may be seen by using the tsk command and
noting it’s priority. This command does not affect the priority of the shell itself,
only die commands executed by the shell.

[PRI]

Utilities

PROMPT?

PROMPTT - Display tty number

Syntax:

promptt

• This is a local shell command •

Description:

The PROMPTT command will toggle the display of your tty number before the
standard shell prompt. It is useful when you have several windows mounted on the
console which may be difficult to tell apart.

3 $ will be displayed if you are logged into $tty3

Utilities

[PROMPTT]

none

PRTSC saves the console screen, then pops-up a menu in a full screen window
which allows you to select one of several options. One of these choices allows you
to make a hardcopy of the saved screen. Another allows you to save the screen
contents in a file.

This command is invoked automatically by QNX whenever the user types
Ctrl-Alt-PrtSc on the console keyboard. The screen is restored automatically when
PRTSC terminates. PRTSC can therefore be used as a means of executing
commands without destroying the contents of the screen.

A file of additional menu items can be created by the user, which will be added to
the menu already supported by PRTSC. This file is called /config/prtsc.cfg and
consists of one or more text lines. The first 12 characters are used as the menu
identifier. The command which starts in the 14th column will be executed when
this menu item is selected. A sample file would look like:

Calculator

Mail

Cardfile

JkP

Chat

calc +f

mail

cardfile

chat

[PRTSC]

Utilities

PETSC

With the above data in the file /config/prtsc.cfg, PRTSC would display a menu
like:

a) Do Nothing

b) Print Screen

c) Save Screen

d) Calculator

e) Mail

f) Cardfile

g) AP

h) Chat

Typing the indicated letter will perform the associated function. Also, an inverse
"idee cursor can bo moved with the UP and DOWN arrow keys. Typing Enter will
select the highlighted function.

See Also:

CALC

Utilities

[PRTSC]

PWD

PWD - Print Working Directory

The PWD command will display the complete pathname of the current directory.
Under the network version of QNX, the pathname will be preceded by your node
number in square brackets.

See Also:

[PWD]

Utilities

qcp [device] SEnd [options]* srcJile[,dst Jile] [x-indexJile] ^
qcp [device] SJSceive [options]* [^forcedfilename I p—prefix]

device

-make„dir

+newest

+relaxed_timing

+today’s_date

-s-verbose

-verbose

filename

p-prefix

s=packet_size

Name of QNX device to use (default: current device).
Suppress making directories for received files.
Receive only files that are newer than existing files.
Double timeouts and quadruple retry counts.

Place today’s date on received files.

Display error status while transferring files.

Display nothing during the transfer.

Force received files to have this name.

Place this prefix on the names of any received files.
Set size of transmitted data bursts (default: 2048).

QCP provides the error checked file transfer protocol needed by Qtalk, Qterm or
QCL ( QNX Communications Language) to transmit or receive files. The QCP
protocol achieves both high efficiency on packet switched networks and high
reliability due to the use of 16 bit CRCs (Cyclic Redundancy Check). QCP is
specific to the QNX environment and automatically sends files with their path
name, attribute, permissions and date fields intact.

QCP is another one of those commands that needs the timer administrator task
running in the background. This can be accomplished by executing the command:

timer &

or by placing it in the sys.init file so that it is always present.

When connected to another QNX system through a serial port and running Qtalk or
Qterm, files can be transferred from the remote system to the local system by
giving the remote system a command of the form:

Utilities

[QCP]

QCP

qcp se filel file2,file3 x=file4

This example would send filel, send file2 and cause it to be received with the
filename "file3” and then send all the files named in the index file n file4". Index
files are easily created with the LS or FILES command. The Qtalk and Qterm
programs will automatically start QCP on the local side to receive the file. To
explicitly invoke QCP to receive a file, a command of the form:

qcp $mdm re

should be given. This would start up the QCP task such that it would receive the
file from the $mdm device.

To send files to the remote system, Qtalk or Qterm can be commanded to invoke
QCP with the appropriate options to send the file. Before starting the QCP send,
the remote side must have a QCP task in a receive state. This can be accomplished
by giving the remote system the command:

qcp re

If the send side of the QCP file transfer is being explicitly started from another
task, rather than automatically from within Qtalk or Qterm, the send command
would look like:

qcp $mdm se filename

This would send the named file(s) through the $mdm device using the QCP
protocol.

While a QCP file transfer is in progress, it can be aborted by pressing the space bar
or the escape key. QCP will provide a prompt to which a ’y’ can be supplied to
abort QCP. If a remote QCP in a receive state must be shut down, the control
character sequence A V A X A X will abort it.

See Also:

FILES LS QTALK

[QCP]

Utilities

QTALK - Talk over Communications Line

Syntax;

qtalk [system] [options]*

Options:

system - The name of a system you wish QTALK to call.

+echo - Local echo.

+iflow - Support flow control on the incoming data.

-parity - Ignore 8th bit of received characters.

c-hh - Specify character which invokes QTALK commands.

(Default is CTRL-A).

d=delchar - Replace ASCII RUBOUT with delchar .

1 =logfile - Log session into "logfile".

m -modem - Name of async device (Default: $mdm).

h-buf_size - Size of receive buffer. (Default: 4000).

k=hh - Kick character.

p-hh - Pause or turnaround character.

o-option - Option(s) to be used for file transfer protocol.

Examples:

qtalk home - Phone home. (Pretend you are E.T.).

qtalk +e d=08 - Communicate with a machine which does not echo (half

duplex) and expects an ASCII BACKSPACE to delete
characters.

qtalk i=$lpt - Communicate with another system with hardcopy record,
qtalk k=ll p=0d - Prepare to send a file to a mainframe which sends Ctl-Q
when ready for input.

qtalk m=[l]$tty6 - Use the $tty6 serial port on node-1.

Utilities

[QTALK]

QTALK

QTALK allows QNX users to communicate with other computers via a modem.
The destination may be another host computer (mainframe) in which case QTALK
allows your computer to be used as a terminal. QTALK also allows two QNX
users to communicate and transfer files.

QTALK will send any characters typed on the keyboard to the other system over
the modem. Any characters received by the modem are displayed. In local-echo
mode, typed characters are echoed on the display as well as being sent over the
modem.

A recording of a QTALK session can be filed using the 1= option.

l=$lpt

i=/tmp/logfi!e

A special COMMAND character allows special modes and options to be set while
within the QTALK environment. This special character defaults to control A
(Ctrl-A), unless changed with the c= option before entering QTALK. The character
following the COMMAND character is interpreted by QTALK to perform some
special function. If the next key is not a valid QTALK command, then it will be
echoed to the modem. Hence Ctrl-A Ctrl-A will send a single Ctrl-A to the
modem.

The QTALK commands can be one of the following:

b - BREAK

Send a break over the modem. Breaks may also be sent by pressing the
BREAK key (Ctrl-BREAK on the console keyboard). NOTE: if you
press the break key four times in a row, without typing any intervening
characters, QTALK will terminate, as if you had invoked the x (exit)
command.

c - CHANGE DIRECTORY

QTALK will prompt you for a new directory name, and will attempt to
change directory to it. If successful, the specified directory will become
die current "working directory" (see the command PWD), for the dura¬
tion of QTALK, or until you change directory again. When QTALK
terminates, your current working directory will revert to the directory
you were in when QTALK was invoked.

[QTALK]

Utilities

QTALK

d - DIAL SYSTEM

QTALK will prompt you to enter a system name. If that name is found
in the dial.dir file, the associated string (usually a modem dialing
command) will be sent to the modem. If you enter a question mark (?)
for the system name, the contents of the dialing directory will be
displayed, and you will re-prompted for the system name. Pressing
return, without entering a system name will abort the dialing command,
and return you to normal communications mode.

Dialing is implemented by looking up the system name (which can also
be specified on the command line when QTALK is invoked) in a file
Iconfigl dial.dir. This file is of the form:

system-name dialing-command

The system name may be any string of characters (except for spaces and
tabs) of any length. The dialing command is any characters (including

spaces and tabs) which are sent to the modem. Typically this would be
the dialing command for your modem, and the phone number to dial.
The system name and the dialing command are separated by one or
more spaces and/or tabs. An example dialing directory entry that
instructs a Hayes-compatible modem to call the QUICS update system
would be:

quics ATD16135910934

e - ECHO

The local echo feature is toggled. Some mainframes expect the
"terminal" to perform local echoing.

h - HANGUP

The CTS/RTS lines will be lowered for approximately 1/2 a second.
This permits modems which support hardware hangup to do so.

1 - LOG

Begin or end logging of this session. If no log file is open, then QTALK
will ask for the name of a file to log into. If logging is already in
progress, then it will be terminated and the log file closed. LOG will
record every character which is sent OR received in the log file.

o - TRANSFER OPTIONS

QTALK prompts for the options to use when invoking a file transfer
protocol. Often, the QCP "+newer” option is used to condition the
transfer to ignore files which are older than the copy you already have
on disk. This can be a real time-saver when downloading an update
from QUICS (the QNX Software Update system).

Utilities

[QTALK]

QTALK

For example:

Transfer options: +n
p - PARITY

Ignore parity (top bit) of received characters. If this option is already
set, then turn it off.

q - QUIT and HANGUP

This does a hangup command (see above) before exiting from QTALK.
s - SEND A FILE

Send a file using the QCP file transfer protocol. This sends a file to
another system running the same protocol, which is far more secure
than simply writing the file to the modem.

QCP is a very secure, fast protocol specifically designed for QNX. It
permits information about the file (the file date, attributes and
permissions) to be transferred, as well as the file contents. QCP is
ideally suited for use over public packet switch (X.25) networks, as well
as direct modem-to-modem connections. If communication errors are
encountered, portions of the file will automatically be resent until the
far end acknowledges correct reception of the file.

More than one file can be sent by specifying x=filename when QTALK
asks for the file to send. This file will contain a list of files to send, one
per line. You can also specify more than one filename, separated by
spaces.

QTALK allows you to follow the name of the file to send with the name
of the destination file separated by a comma. This is also true for file
names within an index files (x=). For example:

Send file(s)? filel mam.c,new_main.c

will send the file "filer* as "filel" and the file "main.c" with the name
"new_main.c". If no new name is given, then QTALK will create a file
with the same name as the file which is sent.

Files received by QTALK using the QCP protocol will have the same
attributes and date as the file on the sending machine.

Protocol transfers require that the modem port be configured for 8 bit
data (see the STTY command).

[QTALK]

Utilities

QTALK

u - UPLOAD TEXT

Upload text to another system. This permits text files to be sent to
another computer using a simple handshaking protocol based on the
pause and kick characters, specified on the command line. If local-echo
is not enabled (see the e command, above), QTALK will wait for the
character to be echoed by the remote system, before sending the next
character. If local-echo is enabled, the text will be written to the
modem with pauses only when the pause character is encountered.

A text upload may be aborted at any time by pressing the Escape key
(ESC), or by pressing BREAK (Ctrl-BREAK on the console keyboard).

NOTE: you must specify both the pause and kick characters to use the
upload handshaking protocol. If either (or both) characters are not
defined, then it is the same as issuing a w (write) command (see below).

w - WRITE

Write a file to the modem. The file will be transmitted over the modem,
and also echoed on the display if local echo is enabled. WRITE also
allows files to be transferred to mainframes or other users with
handshaking, but no error checking (described below).

Writing to the modem may be aborted at any time by pressing the
Escape key (ESC), or by pressing BREAK (Ctrl-BREAK on the console
keyboard).

The primary difference between upload and write is whether or not to
wait for the character to be echoed by the remote system, before sending
the next character.

x - EXIT

Exit from QTALK without performing a hangup. It is probably a good
idea to get in the habit of using the q (quit and hangup) command for
leaving QTALK, unless you really mean to not perform a hangup.

! - Execute a shell command

This permits you to execute any command from within QTALK.

Typical usage of this would be to execute the Is command to discover
what files are in your current directory prior to uploading or sending
some of them, or to execute non-native file transfer protocols (such as
Xmodem or Kermit) from within QTALK.

When communicating at high baud rates, the logging facilities may interfere with
apparent response. The QNX operating system internally buffers up to 256
characters while data is being written to a file or printer. QTALK adds another

Utilities

[QTALK]

QTALK

level of input buffering which can hold a larger number of characters. This buffer

size can be changed with the b= option on the command line. The default buffer
size is 4000 characters. Very high speed modems, or logging on slow printers or
floppy disks may cause this buffer to be overrun, in which case some characters
may be lost. Input flow control can be enabled (see STTY) prior to invoking
QTALK, or at the time QTALK is invoked using the "+i" option, to prevent
characters from being lost in these cases, provided that the machine which is
sending the data supports flow control of its output.

Two methods are supported by the QTALK utility which allow users to transfer
files. The simplest method is invoked using the upload, write and log commands
to send and receive text files to/from another system. No error checking is
performed so this method should only be used when communication lines are good
(ie. direct connect lines or local modem connections). The send and receive
commands use a more sophisticated protocol which includes error checking and
re-transmission when transferring files to other systems.

Two parameters can be specified on the command line to select the protocol which
is used by the upload command. These parameters are:

p =hh - PAUSE or turnaround character (hex). If upload detects this

character in the file it is sending, it will be sent and QTALK will
pause waiting for a KICK character to be received. Setting PAUSE to
a CR (0D hex) will cause upload to send one line at a time,
k =hh - KICK character (hex). This character is used in conjunction with the
PAUSE character by upload to handshake with other computers
when transferring files.

These parameters allow the protocol to be adjusted according to the characteristics
of the hardware at each end.

The write command can be used to transfer files to other systems which can accept
input without needing to pause for any form of handshaking. For slower systems
(especially systems running full-duplex), the upload command is more
appropriate. The log command can be used to take "snapshots" of data from a host
mainframe at slow speed.

To send a file to a mainframe, the user can use QTALK to enter into input mode of
the mainframe’s editor. The upload or write command can then be used to send a
QNX file to the mainframe. QTALK should be invoked with p=0d to cause one
line at a time to be sent. KICK should be the prompt character which is printed by
the mainframe editor whenever it is ready to receive a new line. On some
mainframes this may be a Ctl-Q or it may be a prompt character such as a dot (.).

[QTALK]

Utilities

QTALK

The d= option is very useful when communicating with mainframes which have a
different RUBOUT character than you are used to. Many mainframes use the
backspace key (hex 08) to erase a character. QNX systems default to the ASCII
RUBOUT character (hex 7F). Typing:

qtalk d=08

will cause QTALK to translate your RUBOUT key into backspace automatically.

See Also:

CHATTR

QCP

STTY

Utilities

[QTALK]

QUERY - Query the utilization of a disk

Syntax:

query [[node]drive] [-address] [+display] [+hex] [+visual]

Options:

-address - Don’t print addresses at the side of the bitmap
displayed with the +display option.

+display - Display bitmap using character graphics and decimal addresses.
4-hex - Use hexadecimal notation for the 4-display option.

4-visual - Maintain a real time bitmap display.

Examples:

query

query 3
query 3 4-d
query [2]1 4-v

Description:

QUERY allows the user to determine how much room is free on a disk. QUERY
will examine the bitmap of the disk on the indicated drive and report how many
blocks are used and what percentage of the total available blocks this corresponds
to.

The 4-visual option is useful for monitoring how much space is left on a ramdisk or
floppy disk while files are being copied to it. If the bitmap is too large to display
on a single screen, the visual update is terminated. To exit from the continuous
display mode, press any key.

See Also:

CHKFSYS

[QUERY]

Utilities

QUEUE - Implement queued message passing in QNX

Syntax:

queue Oglobal] [p=signal j>ort] &

Options:

+global - Globally register the queue manager.

p^signal jport - Specify which port to use. If unspecified, the
first free port will be used.

Description:

QUEUE implements queued message passing in QNX. It should only be started if
needed by applications. Although no QNX Software Systems applications are
using QUEUE (as of January, 1988), this may not always be true. A number of 3rd
party application developers are using QUEUE. If you have any doubt as to
whether or not you should run QUEUE, check the documentation for the applica¬
tions you wish to run, or contact the vendor or QNX Software Systems technical
support.

If you ever need to terminate QUEUE, use the SLAY command:
slay queue

See Also:

Queue management routines in the QNX C compiler manual

Utilities

[QUEUE]

RM - Remove files

Syntax:

rm file* [+interactive] [+recursive]

Options:

+interactive - Display each file and ask whether
to remove.

-{-recursive - If a passed file is a directory

the entire contents of the directory
(including subdirectories) will be
removed.

Examples:

rm *.o

rm dirl dir2 +r

rm * +i
rm "test"

Description:

RM removes one or more files from a directory. Removal of a file requires write
permission on the file itself.

If a designated file is a directory, an error is printed unless the -{-recursive option is
specified. In that case, RM recursively deletes the contents of the specified
directory and then the directory itself. Note that RM invokes the WS command for
recursive removal. Placing the RM command in ramdisk can speed this process.

The -{-interactive option will cause RM to print the name of each file it is about to

remove. A single character response of the letter ’y’ (for yes) will remove the file.
Any other response will leave the file untouched. This option may be combined
with the -t-recursive option.

- Remove all object files.

: +I •

- Remove dirl and dir2. If they are
directories remove all files and
directories under them.

Query for each file.

- Query whether to remove each
file in the current directory.

- Remove all files containing the
word ’test’ in their name.

[RM]

Utilities

RM is a more advanced version of the command FREL.

See Also:

DREL FREL
RMDIR WS

Utilities

[RM]

RMDIR

RMDIR - Remove directories

Syntax:

rmdir directory * [+interactive]

Options:

+interactive - Display each directory and ask

whether to remove.

Examples:

rmdir test

rmdir test 3:/tmp

Description:

RMDIR will remove a directory from the disk. Only empty directories can be
released. If the RMDIR command verifies that the directory is empty, then the
space used by the directory will be reclaimed.

If a directory is to be removed which is at the top level (root), it is usually
necessary to specify the correct drive prefix as in the last example.

The +interactive option will cause RMDIR to print the name of each directory it is
about to remove. A single character response of the letter ’y* (for yes) will remove
the directory. Any other response will leave the directory untouched.

See Also:

[SAC]

Utilities

SEARCH - Define or Query the Disk Search Order

Syntax:

search drive* [+remote]

Options:

^remote - Define search order for requests from
other nodes on the network.

Examples:

search - Query the current disk search order

search 5 3

- Define the disk search order such that drive 5 is searched
first, followed by drive 3.

search 3 +r - Set remote search order to be drive 3.
search 3 [5]

- Search drive 3 then use node 5’s remote search order.

Description:

SEARCH defines the "order” in which die operating system scans disk drives

while opening files.

A default disk search order is setup at boot time by the operating system. If you
boot from floppy diskette the disk search order is linear over your floppy drives.

search 1
’ or

search 12

if you booted from hard disk your search order will be disk 3 which is mapped to
the the disk partition you booted from. Please read the section on hard disk
booting for more details.

search 3

Utilities

[SEARCH]

If you boot over the network your search order will the remote node you booted
from.

search [nodeJbootedJrom_]

It is usually desirable to change the search order to include mounted ramdisks and
hard disks. Most users do not search the floppy drives at all.

Adding new drives to the system with the MOUNT command will not
automatically include the drive into the system search order. SEARCH must be
used before these drives will be automatically scanned when loo king for files. Files
can still be accessed on drives which are not included in the search order by
preceding the filename with a drive prefix.

If a number in square brackets is included, then the remote search order on that
node is used.

Requests for files on a local hard disk can come from two sources. They can
originate locally from tasks on the same machine or remotely from tasks on other
machines. The +remote option determines the search order which will be used for
remote requests. A local ramdisk is usually excluded from the remote search
order.

See Also:

MOUNT

NACC

PATH

[SEARCH]

Utilities

SH - Execute Shell Commands

Syntax:

sh [options]* filename [ arguments ]*

Options:

4- back - Suppress the display of background task ids.

4-menu - Internal use only.

4-qdb - Internal use only.

4 -initial - Execute the next argument as a command using
the EC command, then accept input from the
keyboard.

4 -restrict - Restrict the commands and command line syntax allowed.

The commands cd, path and the characters >, / and A

become invalid.

4 -string - Execute the next argument as a command then terminate.
4 -transform - Cause the shell to transform itself into
the first command it executes.

4 -verbose - Print each command line before executing.

Examples:

sh commands

sh /cmds/mycc test.o c=test l=/lib

Description:

SH is the command interpreter (referred to as the "shell") and acts as the interface
between the user and QNX. SH can take commands interactively from the
keyboard or from a batch file. The following documentation concerns itself mainly
with batch file operation. Interactive operation is described in a chapter in the
QNX manual. This chapter also contains background information on the shell
which is recommended reading.

SH allows the user to execute the commands found in a file as if they were typed
on the keyboard by the user. Each line in the file will be executed as a command
by the shell. The shell’s arguments can be included into these commands by
referencing them as #1 #2 ... #9. Any instance of #1 will be replaced by the 1st.
argument on the command line. For example, in the second example above, #1 is
replaced with "test.o”, #2 will be replaced with "c=test" and #3 will be replaced

[SH]

Utilities

with "l=/lib" before the commands are executed. #4 through #9 in this example

will be replaced with the null string. The complete list of # macros are as follows:

- number of arguments

- task number of shell

- task id of shell

- exit status of last command

- task id of last background task

- cyclic number which changes each second

- group number of user

- accept a line from the keyboard

- member number of user

- node number

- cpu type

- tty number

- userid of user

- qnx version number

- name of shell command

#1 to #9

- arguments passed to shell command

- all arguments #1... #nn

The #p macro contents is defined as follows :

PC 1

AT real mode 2

PS2 4

old HP Vectra 5

PS2 model 30 6

AT Protected mode 42h

PS2 protected mode 44h

old HP Vectra Protected mode 45h

SH allows a user to define his own commands. Commonly repeated sequences of
commands can be grouped into one command file thereby allowing the user to
execute this group of commands with a single command.

An example of a command file would be a file called "rename" which contains the
following line:

chattr #1 n=#2

The user would then type

sh rename bill joe

Utilities

[SH]

to change the name of file ’’bill" to "joe". If the command is used quite often, the

user can remove the need for typing "sh" every time by giving the command file
execute permission with the CHATTR command (use: "chattr rename a=+e").

The user can now type:

rename bill joe

Each command will return a value when it terminates. This value will usually be
zero if the command terminates normally.

The +i option is used by the LOGIN command to pass the initial command to
execute which was read from the password file.

If you type a Ctrl-d to the shell it will terminate. This is useful when invoking the
shell from within the editor (or any command) by typing a Ctrl-z. Typing a Ctrl-d
will return you to your application.

The complete list of shell batch commands follows:

back - suppress background lid

When you run a program in background using the & symbol the shell will
normally display the taskid of the background task created. In shell files this may
not be desirable. The BACK command suppresses this display.

base number - base for number expansions

When an integer shell variable is displayed it will be displayed as either a 4 digit
hexadecimal number or a 5 digit unsigned number. The argument for base should
be either 10 or 16.

break task_id - break a task

The indicated task will be killed by setting a break exception on it. You may
obtain the tasks identity with the TSK command.

cd [directory] - change directory

Since each task has its own directory this command must be handled by the shell.
Placing it in a command which loaded off the disk would change the directoiy of
the new task loaded but NOT the directory of the shell. This should be kept in
mind when escaping from a command via Ctrl-z. You can NOT change your
directory then return back with the new directory in effect. This is documented in
detail in the utilities section of your binder.

debug [text] - debug a command

If text is missing then the debugger is invoked with the data and code segments
pointing to 4K of free memory. If text is present then the debugger is invoked after
loading the command indicated.

[SH]

Utilities

debug Is

The debugger must be mounted or the request for debug is ignored. Please read
the debugger documentation first! If you don’t, simply type ’g’ followed by a
carriage return to return from the debugger.

defpipe path ~ pipe temp files

The DEFPIPE command allows you to change the pathname where temporary pipe
files are placed.

defpipe my__pipe

The default is

defpipe /tmpL#n#$

ec shellJile - execute sh file

This is especially useful in the password file where you will often see a line such
as

ec userinit

EC commands cannot be nested,

else - conditional

The ELSE command precedes a group of one or more commands terminated by an
ENDIF which are to be executed if the preceding IF condition was false. An ELSE
must be within the scope of a preceding block IF command. For example

if +f #l.c then

cc #1 m=map

sort map f=l,3 +r
else

type File #Lc does not exist
endif

endif - end a block if

The ENDIF statement ends a list of statements following a block IF or an ELSE.

Utilities

[SH]

exit [number] - exit shell with status

The EXIT command will exit the shell and return back either the indicated status
or the status of the last executed command if status is omitted. The status argu¬
ment is assumed to be in the current base set by the BASE command.

goto label - transfer control

The GOTO command transfers control to the line following the one containing the
indicated label. A label is entered as a colon (:) followed by label name of up to 8
characters. For example

:loop

type This is a loop
goto loop

If the label does not exist then the shell file will terminate.

if test cmd - conditional

The IF command allows conditional execution of QNX commands. There are two
forms of this command. If the argument command is the keyword THEN, then
commands on the following lines until an ENDIF are considered to be within the
scope of the IF. This is called a block IF. Otherwise, only the indicated command
is conditionally executed. There can be no ELSE or ENDIF. If the TEST is true
then the command is executed.

if +f pathname

command

if +d pathname

command

if +m pathname

command

if +a nodeid
if eq argl argl
if ne argl argl
if It argl arg2
if ge argl arg2

command

true if pathname is a file
and exists

true if pathname is a directory
and exists

true if pathname has the modified
bit set

true if node is alive

true if argl is identical to arg2

true if argl is different from argl

true if argl is less than argl

true if argl is greater than or equal

to argl

The arguments in the last two forms may NOT contain an embedded blank unless
the argument is enclosed in double quotes.

if eq "#1" "Clarke Kent" frel

You may match a null (or missing) argument using the following trick,
if eq abc #labc type Argument missing

[SH]

Utilities

As a final warning, remember that the # shell variables which result in a number
are always expanded to 4 places if hexadecimal and 5 places if decimal.

if eq #& 0000 exit

It is possible to nest block IFs. •

if eq #1 abc then
if eq #2 def then
type abc def
else

type abc NOT def
endif

else

if eq #2 def then
type NOT abc def
else

, type NOT abc NOT def
endif
endif

kill taskjd o.. - kill a task

The indicated tasks will be killed. You may obtain the tasks identity with the
TASK command. This is included in the shell to allow you to kill a task even
when there are no free task descriptors in the system to create a new task. The
escape sequence #& refers to the last background task you created.

kill #&

If the first argument starts with a plus sign (+) it is taken as a system exception to

set on the remaining taskid’s specified. For example

kill +0001 050c -set exception hangup on task 050c

Refer the to chapter on MULTI-TASKING for more information on exceptions.

You may wish to refer to the SLAY command to remove a task by if s name
rather than if s task id.

entty tty cmd - create task on another tty

Utilities

[SH]

or LOGIN on that console.

mount console $con2
ontty $con2 sh
OR

ontty $con2 login

If this command is combined with the syntax of remote task creation, then the
remote node should precede the ONTTY. You may also specify the node number

as part of die device name.

[4] ontty $con2 ed file
ontty [4]$con2 ed file

These will create the editor on $con2 of node 4. The editor will attempt to read the
indicated file using the search order on node 4.

passon - password protection

The PASSON command will cause the LOGIN command to look for the file
"/config/pass" and enforce password protection on login. If this file does not exist
you will be unable to login.

Once passwords are enabled, they cannot be turned off.

path searchpath - change search path

Each time a command which does not start with a slash is executed by the shell a
list of directories is searched for an executable file. The default is "/cmds/"
followed by the current directory. This may be changed using the PATH
command followed by a list of directories surrounded by exclamation marks. For
example, to search the current directory followed by "/cmds" followed by
"/user/cmds"

path ! !/cmds/!/user/cmds/!
and to return to the default

path l/cmis/l! OR path

You may print your current search path with

path ?

pause - pause for carriage return

The PAUSE command will pause and wait for you to type a carriage return. When
used with the TYPE command it gives you the opportunity to change disks or
perform some other action before executing the next command.

[SH]

Utilities

pri [+1 -^number - set priority . . , ,

Set the priority of commands executed by the shell. A ’+’ increases it while a -

decreases it. If no argument is given the priority is set to the default of eight. The
priority must lie within 4 and 15 with 4 being the highest priority. Smaller values
have higher priority. The command.

pri -1

will ADD one to your priority number which will cause the command to ran at
LOWER priority. The priority number may be seen by using the task command

and noting it’s priority. This command does not affect the priority of the shell
itself, only the commands executed by the shell.

prompt! - display tty number

The PROMPT command will toggle the display of your tty number before the

standard shell prompt. It is useful when you have several windows mounted on the
console which may be difficult to tell apart.

3 $ will foe displayed If you are logged into $tty3

setvar op var val - set variable

The user variable is set to a new value based upon the op type.

String Variables
setvar = s« value

- assign string

setvar | s« value

- concatenate string

setvar = oranges
setvar | ”, apples”

Integer Variables
setvar = L number

- assign number

setvar + L number

- add by number

setvar - L number

-subtract by number

setvar x L number

- multiply by number

setvar / L number

- divide by number

setvar % L number

»modulus by number

setvar = 10 123

- set 10 to 123 using current base

setvar = 10 0tl23

- set iO to 123 using base 10

setvar = iO 0x123

- set 10 to 123 using base 16

setvar + il #i0

- add iO to 11 updating il

setvar = sO a#k

- get line from keyboard, the Vis

to ensure some data is assigned in

[SH]

Utilities

case a blank line is entered.

sharoff - don 9 t share code segments

This option will stop the sharing of code. See SHARON for details.

sharon - share code segments

This option will cause the task admin to scan the code table and check if a task is

already loaded into memory. If so, it will link to the existing code and only load
the data from the file. Note that this code sharing only occurs for commands under

Vcmds 5 or those specified with a leading 7 s . This the default when the system

boots.

shift - shift # args down one

The SHIFT command allows shell commands access to arguments beyond #9.

Each argument is shifted one position to the left. #0 becomes #1, #1 becomes #2,
... and #9 becomes what would have teen #10. The following shell command will

print any number of arguments passed to it.

:loop

if eq ## 0000 exit 0

cype #i

shift

goto loop

stype [text]* - type arguments

Identical to TYPE, however, no carriage/linefeed is printed.

sysup - set system up flag

The SYSUP command will set die system up flag. Until this flag is set, Ctrl-z and

Breaks will be ignored on terminals, preventing anyone from logging in, or
terminating execution of the sys.init file. This flag is automatically set after the
7config/sys.init’ file has run to completion. In some cases a user may wish to
invoke a command in the ’sys.init’ file (like a menu shell) which prevents it from
finishing. In this case you may force the system up placing the SYSUP command
in your ’sys.init’ file before this command is invoked.

then - conditional

The THEN command can only be used on a line containing an IF command. It
signals the start of a block IF.

trap [label] - trap keyboard breaks

The TRAP command allows a shell file to trap keyboard breaks. After executing

each statement the shell checks to see if a keyboard break has been typed. If so,

execution is transferred to the indicated label as though a GOTO statement had

[SH]

Utilities

been executed. If the label argument is missing then the break is ignored. If the
indicated label does not exist then the shell command will terminate.

trap - ignore keyboard breaks

trap + » since label + will never occur

this will cause the shell command
to terminate on a break

trap loop - transfer control to the label doop

The following will print out a message until a break is typed.

trap stop
:loop

type Type break to stop me

goto loop

:stop

type Ok, you stopped me!

type [text\* - type arguments

The arguments following the command are displayed on the terminal, followed by

a carriage return. This is often used within command files for informational
purposes.

verbose - toggle verbose mode

The VERBOSE command toggles verbose mode of the shell. In verbose mode the
shell will echo each line it reads to your screen before it executes it.

zeros on/off - toggle verbose mode

The ZEROS command turns on or off the printing of leading zeros when
expanding numbers from shell variables. By default they are on to allow correct
string comparisons in the IF command. They are usually turned off to generate

text or pathnames which is more readable. For example.

base 10
zeros off

type "You are on tty #t H

See Also:

Utilities

[SH]

SHARON/SHAROFF - Do/don’t share code segments

Syntax:

sharon

sharoff

* This is a local shell command •

Description:

When SHARON has been enabled, the task admin will scan the code table to check
if a task is already loaded into memory. If so, it will link to the existing code and
only load the data from the file. Note that this code sharing only occurs for
commands under Vcmds’ or those specified with a leading 7’. This is the default

when the system boots. SHARObr disables code sharing.

Utilities

[SHARONSHAROFP]

SIZE - Display the size of a file

Syntax:

size [file I x=file]*

Options:

file - Name of a file to size

x-file - Index file containing a list of files to size

size teste

size inventory mailing list x=misc_files

Description:

SIZE will calculate the total number of characters in each of the given files.

If more than one filename is given, then SIZE will also report the total number of
characters and lines in all the files.

The x= option allows a file containing a list of filenames to specify the files to
count. This "index" file may be the result of redirecting the output of the FILES
command (with -v option) or the LS command (with the +f option).

See Also:

FILES

[SIZE]

Utilities

SLAY - Kill a task by name

Syntax:

slay [taskjiame] [options]*

Options:

+break_only
+dump
+hold

“hold

+query_always
“query
+remote
-son_kill

+fid

-verbose
i=task_id

n -nodejmm
i~tty_num
s=system_exc
u~user_exc
p =priority

Examples:

slay spooler n=2 - Kill spooler task on node 2.

slay dragon t=3 -q - Kill dragon task on tty3 without querying first.

slay test +d - Force memory dump on a test program.

Description:

SLAY is used to kill a task by name rather than by the task identification number
(tid). This saves the user from having to first run the TSK utility before issuing a
KILL command. Task names are specified without the path. An example would be
a task called "/cmds/list" that the user wished to kill. Entering "list" as the task
name would be sufficient to allow SLAY to find and kill it.

There are many forms of this command. The simplest (and probably most often
used) form of the command is of the form:

- Set only a break exception on the named task.

- Force task to perform a dump.

- Hold the named task.

- Unhold the named task.

- Always query before killing a task.

- Don’t query before killing tasks.

- Also kill tasks started by remote nodes.

- Don’t kill tasks which have son tasks running.

~ Don’t kill the task return it’s task id to the shell.

- Suppress messages about missing tasks.

- Select task based on taskjd.

- Search for named task on this node.

- Limit task search to this tty.

- System exception bits value (hex)

- User exception bits value (hex)

- Assign new priority to selected task(s)

Utilities

[SLAY]

SLAY

slay ta$k_name

This command will locate the task bearing the specified name and if only one is
found both the KILL and BREAK exceptions will be set on it. If more than one
task bears the specified name, the user will be prompted for a yes / no response for
each task. When each task is listed in this form, the task name, tid, node number,

tty and user group / member numbers will also be displayed to help the user make
a selection. If no task name is specified, all tasks in the system will be matched and
the user will be prompted for each of them. Answering die prompt with any
character other than a *y* or ’n’ (with ’q\ for example ) will cause an exit from
SLAY.

By default, tasks that are running remotely from other nodes in a network will not
be included in the scan for matching tasks. If these tasks must also be killed, use
the +remote option.

In more detail, the options supported by SLAY are:

+break_only - Normally, SLAY will place both a break and a kill exception
on the named task. This option will cause only the break
exception to be set on the named task.

+dump - This option sets a quit exception on the named task. If the

dumper task has been installed a "snapshot" of the segments
that make up the named task will be written to disk. QDB,
the QNX Source level debugger, can then be used to browse
through the execution environment at the moment of the
dump. Please consult the QDB documentation for details on
dumper.

■fhold -hold - The hold option allows this utility to set or remove a hold

status on the named task. One particularly useful example of
this option is for a program which wishes to temporarily not
have the CLOCK program display the time in the upper right
comer of the screen. Issuing the command:

slay clock +h

would stop the time display. Once the application was
finished, it could resume the time display with the command:

slay clock -h

+query - This option forces SLAY to query before killing the task.

even if only one task is found with a matching name. This
option is useful for viewing the other task information that
SLAY will present before killing it.

[SLAY]

Utilities

-query

+remote

-son_kill

+tid

-verbose

m-nodejmm

i=tty_number
s =system_exc
m=user exc

SLAY

Force SLAY to not query if multiple occurrences of the same
task name exist. This makes SLAY useful in shell

commands if the environment is known to be appropriate for
running SLAY in this manner.

This option will allow killing local tasks that were started
from another node. This option is needed to allow a user on
his workstation to kill tasks that other network users have
started on his node.

This option will suppress killing tasks that have son tasks. A
typical usage of this command would be within a shell
command that shuts down shells on other tty devices. Setting
this option would prevent SLAY from killing those shells if
they had other tasks (such as editors ) running. Running
SLAY with the 4-query option also set, will cause SLAY to
prompt for a forced kill even if the named task has sons.

This option will cause SLAY to return the task id of the first
task which bears the requested name. If the named task does
not exist, a task id of zero will be returned. This option then
makes SLAY useful for shell scripts and C programs which
wish to determine the task id of a task without having to
resort to elaborate programming. Within a shell program, the
usage would be:

slay task_eame -ft -v
type #?

Within a C program, the SHELL library routine could be
used to invoke SLAY to obtain the task id of a task as
follows:

tid = shell( "slay taskjiame +f -v" );

Suppress messages about a task not being found or having
sons preventing the removal of the task. If the +query option
is set, the prompts will not be suppressed. This option is
useful within shell commands to suppress unwanted output.
This option specifies the network node from which tasks
are to be killed. This option allows convenient removal of
tasks from a remote node without having to have a shell
running on that node.

This option specifies the tty from which tasks are to be
killed. Tasks running from other ttys will not be affected.

Set the specified SYSTEM exception bits on the selected
tasks. See the ’/lib/exc.h’ file for exception bit definitions.

Set the specified USER exception bits on the selected tasks.
See the ’/lib/exc.h’ file for exception bit definitions.

Utilities

[SLAY]

SLAY

p apriority - Change the priority of the the selected tasks to priority.

Using the SLAY command, a very useful shell program can be created to allow a
user at the console to position the first virtual console ($conO) to a particular
directory, execute the shell command and cause all the other virtual consoles to
also be positioned to the same directory. This is an ideal way to begin working
within a particular directory.

Sf This shell script removes shells from other consoles and starts up shells in
the same directory as the current shelL This command can only be run from
" $conO, the first virtual console. It assumes that the virtual consoles
" represent tty devices 0,7 and 8.
if eq #t 0000 then
slay sh t=7 -q -s
if eq #? 0000 then
ontty 7 sh
endif

slay sh t=8 -q -s
if eq #? 0000 then
ontty 8 sh
endif
endif

See Also:

TSK

[SLAY]

Utilities

SLEEP - Sleep for a number of seconds

Syntax:

sleep time

time - Number of seconds to sleep.

Examples:

sleep 60

Description:

SLEEP suspends execution for time seconds. It is useful in shell files where a delay

is needed. For example

"Take a snap shot of all users signed on every 10 minutes.

:loop

sleep 600
who net »users
goto loop

The SLEEP command requires that the timer administrator be running.

timer &

See Also:

TIMER

Utilities

[SLEEP]

SLICE - Set the timeslice rate

slice [ numjicks [tick_size]]

numjicks - Number of clock ticks to allow a

task to run before timeslicing (1..255).

The default is 1.

tickjize - Time duration represented by each clock

tick. Valid numbers are 1,2, 5,10,25 or 50
milliseconds. The default is 50.

slice 20 50 - Timeslice every 1 second

slice 50 1 - Timeslice every 1/20 second, but provide

a fast timer tick rate of 1 millisecond.

Description:

SLICE allows the rate at which QNX will timeslice tasks to be altered. A large
timeslice count will allow each task to have a large amount of processor time
before being interrupted by the operating system to run a new task. Large timeslice
counts favor tasks which require a lot of processor time and which perform little
I/O.

Small timeslice values improve interactive response.

The default value of 1 results in task switching at least as fast as every 50 msec
(1/20 sec), which usually provides pleasing interactive response with commands
such as the editor, while still allowing background tasks a fair percentage of the
processor.

User written tasks are able to take advantage of fast timer ticks by setting tick_size
to a value representing the desired fastjick duration. By requesting timeouts in
units of tickjize, where tick_size has been appropriately adjusted, short duration
timeouts can be easily implemented.

[SLICE]

Utilities

SLICE

The current timeslice is displayed by the command:

tsk info

See Also:

TIMER

npoi/’

15fv

Utilities

[SLICE]

sort [file ] [options]*

f =field[ field]*
l-nn

i=terminationjoharacters

+bubble_sort
+descending
+float
+hex
+integer
+replace

-skip_leading_delimiters
+unique

Where:

field is fieldjmmber [. offset [. width]]

Examples:

sort malllngjltst

sort inventory f=l,3.2.2,2,7.1 >$Ipt
sort data ff t= +r +d -s +u
sort keyword +b +r

sort file_list t=/ f=-l

SORT will sort text files based on fields. Lines can be of varying lengths but
cannot exceed 300 characters. SORT uses an in-memory sort and is limited to files
of about 55K characters. For larger files the utility MSORT (merge sort) should be
considered.

- Define sort fields (max 20).

- Max lines to sort (default:1000).

- Characters which isolate fields.

- Use bubble sort.

- Sort in descending order.

- Fields are floating point numbers.

- Fields are hexadecimal numbers.

- Fields are integer numbers.

- Replace file with sorted output.

- Don’t ignore leading spaces.

- Remove duplicate lines.

[SORT]

Utilities

SOET

A field is by default assumed to be a string of characters which are delimited by
spaces or tab characters. The delimiter characters can be changed with the t=
option. The fields can be specified with the f= option, otherwise sorting will be
based on field 1 ONLY. The sorting is based on the ASCII values of the characters
in the file unless the +f, +i or +h options are used. If a one of these numeric op-
tions is specified all fields are considered numeric. To sort on a mix of fields you
should run several sorts. For example:

sort file f=l,2 +r ,

sort file f=3 +f +r

The order and definition of the fields is specified with the f= option. If the field
number is negative it is taken as the nth field from the right (not the left). A value
of -1 with a terminator of V 5 allow you to sort a list of pathnames (output of FILES
command) by their filename only. An offset nn (if given) allows the first nn
characters of the field to be ignored in the comparison. If a width is given as well,
then only a maximum of that many characters will be compared. Offset and width
allow sorting of files which have well defined formats.

If no input file is specified, the SORT utility will take its input from the standard
input. The default output of the SORT utility is the standard output. This can be
redirected to a file or device such as the line printer if desired. The +r option
causes the output of the sort to replace the contents of the original file instead of
sending the output to the standard output.

The sorted output will normally be in ascending order. This can be reversed to
descending order by specifying +d.

The -s option allows the user to suspend the automatic skipping of leading fill
characters. This is particularly useful if the user wishes to distinguish between lines
which start with fill characters (eg. spaces) and those which do not.

The +b option will specify that a bubble sort rather than the much faster shell sort
be used. Bubble sorts have the advantage that order is preserved for identical items.
This may be important for sorting keyword or "index" files.

See Also:

MSORT

Utilities

[SORT]

SP ATCH - Full screen patch utility

spatch file filename
spafch disk drive block
spatch mem segment offset

spatch file /cmds/ls
spatch disk 1 1
spatch mem hOOO 0

SPATCH is a utility that allows full screen editing of files, disk blocks and
memory. The screen will display a 16 by 16 (256) byte image of the data being
examined, similar to that shown below:

Edit Next

Home

3oto Find

Continue

Save Addr Quit

Nov

28 9:37:02 am

000000000

. (new) SPATCH "F

000000010

ull screen patch

000000020

utility”..(synt

000000030

ax)...spatch.

000000040

file. .filename

000000050

....spatch. .di

000000060

sk. .drive. .b

000000070

lock....spatch.

000000080

.mem. .segment

000000090

.offset...(ex

OOOOOOOaO

amples)...spatch

OOOOOOObO

file /cmds/ls

0000000C0

..spatch disk

OOOOOOOdO

1 1..spatch me

OOOOOOOeO

m bOOO 0 . . . (st

OOOOOOOfO

art).SPATCH is a

Utilities

SPATCH

The menu at the top of the screen can be used to select one of the options listed
below. You can either position the inverse cursor to the desired menu item with the
arrow keys and type Enter, or simply type the first letter of the command.

EDIT

Enter the data area. The TAB key will switch between hex and character data
entry. The SELECT (large +) key will return you to the menu. The changed data

is NOT updated to the disk or memory.

Move forward 256 bytes. The PgDn key may also be used.

PREY

Move backward 256 bytes. The PgUp key may also be used.

HOME

Go to the the start of the file, disk or memory. The Home key may also be used.

GOTO ^ _

You will be prompted for an address, 1 ne type of address will depend on the the

source of the data (file, disk, mem) and the address type. Moving past end-of-file
in a FILE may produce unexpected results.

FIND

You will be prompted for a pattern to search for. The pattern may consist of single
characters or two hex digits separated by a space.

61 62 63 d e - match the 5 characters ’abcde’

a b c d e - match the 5 characters ’abcde 5

Typing any key during the search will stop it. CONTINUE

Find the next occurrence of the last pattern found. Usually used after a FIND when

searching.

SAVE

Save the current screen back to the source. Without issuing this command all
changes made using EDIT will be lost as soon as you leave the current screen of
data.

ADDR

Toggle through three address types.

Absolute - Default for FILE

Disk BlockiOffset - Default for DISK
Segment:Offset - Default for MEM

Utilities

[SPATCH]

SPATCH

QUIT

Leave spatch.

See Also:

DUMP

DDUMP

PATCH

[SPATCH]

Utilities

SPLIT - Split a file into one or more files

Syntax:

split [outputJile\* [s=size[ 9 size]*[.]] [<inputJile]

output Jile - One or more output files
s =size[...] - Define number of lines to put into each

output file (default: 200)
input Jile - Source file which is being split

Examples:

spilt small i sma'n2 s=iuGu ciarge

split filel file2 file3 file4 excess <massive s=100 9 20O,1OO

split firstlOO nextlOO <big s=100 9 100.

SPLIT allows files to be split into several smaller files. Normally, the file will be
split every size lines, with the excess going into the last output file. The input file is
the standard input which should normally be redirected from the file which is to be
split.

In the first example above, the first 1000 lines of the file "large" will be placed into
the file "smalll", and the remaining lines will all be placed into "small2".

In the second example, the first 100 lines of "massive" will be directed into "filel",
the next 200 will go to "file2", the next 100 into "file3", and the remainder will end
up in "file4".

The 3rd example will place the first 100 lines of "big" into "firstlOO" and the next
100 lines into "nextlOO". Since the size list ended in a period (.), the remaining
characters are discarded.

SPLIT will only split text files with lines no longer than 1000 characters, and has a
limit of 40 output files.

Utilities

[SPLIT]

SPLIT

See Also:

CAT

[SPLIT]

Utilities

SPOOL

- Spool files to a printer

Syntax:

spooler d -device [p -name] [t =imp dir! ] [+clrhouse] 8c
OR

spooler 55 c -command" [p=name] [i=tmp_dirl] [+clrhouse] &

spool [name] submit [filenamelx-filename] [options]

spool [name] cancel spool Jd

spool [name] hold [next]

spool [name] continue

spool [name] move spool Jd position

spool [name] query

spool [name] stop

spool [name] abort

spool [name] kick

Options:

+clrhouse - If a clearing house is installed on the network,
this option will cause the spooler to use it.
c -command- Name the command used to process and output the file,
(default: spooler prints file).

d -device - Name the device to which the spooler is to output,
p -name - Spooler task number/name to use (default 0).

May be a digit (0-9) or an 8 character name,
t =tmp_dir - Automatically delete any files which are in this
directory after printing. This should be a fully
specified pathname, including node number if necessary.
x-filename - Index file containing a list of files to spool.
filename - The name of the file to spool.
options - Arguments to pass to command.

spool Jd - A spool-id displayed by the QUERY option.

position - The position in the spool queue.

Examples:

spooler c=list & - Create spooler using LIST,

spooler p=nec d=$lpt & - Create spooler with name "nec".

spool su test.c - List file ’test.c’.

Utilities

[SPOOL]

SPOOL

spool sit x=cfiles

- List files named in ’efiles’.

spool sis sales +e s=6 w=80

- List file ’sales’ with options to list.

spool qu

- Query spooled files.

spool ca 24

- Cancel spool file #24.

spool mo 23 1

- Move spool file #23 to the

first position.

spool 1 qu

- Query files spooled to spooler 1,

spool nee qu

- Query files spooled to spooler "nec"

spool hold next

- Finish current list then hold.

spool CO

- Continue printing.

The SPOOL command is the user interface to the SPOOLER task in the system. To

start the SPOOLER task you must run it in background. If you wish to spool to
more than one printer you must run one SPOOLER for each printer. If you do not
specify the spooler name/number it will default to 0.

The SPOOLER may be invoked with the name of a command to run (c=) for each
file printed. This will typically be the LIST command. If you do not specify a
command the files will simply be printed to the standard output (or a named device
using the d= option) with no attempt at formatting or pagination of the data. The
SPOOLER will typically be run on the local machine which contains the printer. It
will register a network wide, global name which will be queried by the SPOOL
command to locate the SPOOLER. The TSK command may be used to print all
global names in the system.

tsk names

You can use the SPOOLER and SPOOL command for purposes other than
printing. For example, you might wish to serialize compiles. This would provide a
batch processing mode under QNX.

The subcommands to SPOOL are listed below. Any subcommand may contain a
spooler number n, to indicate one of several SPOOLER tasks in the system. By
default SPOOLER 0 will be assumed. Only the first two letters of a subcommand
need be specified.

ABORT

Abort the SPOOLER task immediately. The current file being printed will stop
and all spooled requests which have not yet been printed will be lost.

[SPOOL]

Utilities

SPOOL

CANCEL

Cancel the request to print the file with the indicated spool Jd. The spool-id is
listed by the QUERY subcommand.

CONTINUE

Continue printing after a HOLD.

HOLD

Hold the printing of files. If the optional next argument is specified the cuirent file
will print to completion before the hold takes affect. Otherwise, the hold will be
immediate. Once held, printing can be restarted by using the CONTINUE
subcommand.

KICK

Kick the spooler onto the next print request. Any request currently being printed
will be aborted.

QUERY

Query all files awaiting print.

MOVE

Move the file with the indicated spool-id to a new position in the queue. The
spool-id is listed by the QUERY subcommand.

STOP

Stop the spooler after the current file is printed. All queued requests will be lost.

SUBMIT

Submit a file to the spooler for printing. The command arguments will depend on
the print command invoked by that SPOOLER command. This will typically be
the LIST command. Only the name of the file is submitted, not its contents. You
should wait until the file is actually printed before deleting it.

See Also:

COPY

LIST

SPOOLDEV

CLRHOUSE

Utilities

[SPOOL]

SPOOLDEV - Create a Spooling pseudo-Device

Syntax:

spooldev [p =port] [f =configJile] [P=priority] &

Options:

p=port - Port to attach to for timeouts. If not specified, the first

available port will be used,
f -configjile - File to read configuration from.

P= priority - Priority to run the specified command at. This option is
particularly useful for use with QDOS.

Examples:

spooldev 8l
spooldev p=22 &

spooldev f=/config/spool.config.3 &

Description:

SPOOLDEV is an optional system administrator which implements spooling

devices in QMX. Whereas physical devices have hardware associated with them
(such as serial ports), a spooling device is a logical device which becomes the

interface between a program and the print spool queue(s). Anything written to a
spool device ends up in a temporary file, which will be processed by a user
specified command when the file is closed. This command will typically submit
the file to the spool queue using the SPOOL command.

SPOOLDEV is typically invoked with the f= option, naming a file which contains
the specifications for the pseudo-devices which will be created. The syntax of
each line of the file is:

devjiame [command [arguments [directory [timeout]]]]

The devjiame is the name by which that spooling device will be known in QNX.
It is limited to 5 characters drawn from the set of (a-z,A-Z). Numbers may not be
used. The name may optionally be preceded by a dollar sign ($) in the file. If not
present, a dollar sign is assumed.

[SPOOLDEV]

Utilities

SP0OLDEV

The command is used to process the spool file after the spooling device is closed.
Typically, it looks like:

"spool submit"

with the command surrounded by double-quotes ("). This is to "protect" the
embedded space between the words of the command. The default, if the user
enters a null command (""), is "spool submit".

The arguments are used as options to the command to control the appearance of
the printed output. An example of this is shown later.

The directory is where SPOOLDEV writes the temporary files prior to actually
submitting them for printing. The default, if the user enters a null directory (" "), is
"/spool".

The timeout field is optional. If you do not wish to support timeouts, specify 0, or
omit the field. This field specifies the amount of time in seconds, that output must
stop before SPOOLDEV will force a close of a spool file and process it. This
option is designed for applications which open a device for a long period of time
and submit several "print" jobs without opening and closing the device around each
job. A classic example of this is the optional QDOS package. QDOS opens the
printer and leaves it open, although multiple print "jobs" may come from the DOS
programs run under it.

A reasonable value for the timeout would be 30 seconds or more, on the theory that
if any program pauses for that length of time while printing, it has probably
finished.

Each field may be separated by one or more spaces or tab characters. If there are
embedded spaces in a field (such as the command or argument string), the field
must be enclosed in double quotes (").

If SPOOLDEV is invoked without a configuration file specified, it is the same as

invoking it with a configuration file containing the following entry:

$spool "spool submit" "" /spool 0

The following example will help to illustrate the use of configuration files. It
implements a logical device which connects to a Postscript laser printer. These
printers do not except simple text but Postscript programs as input. It is therefore
necessary to take text output and turn it into a program which will then drive the
laser printer. QNX provides a command called LPS which does just that and we
will use it in this example.

Utilities

[SPOOLDEV]

SPOOLDEV

Line 1 interfaces to a simple dot matrix printer. Line 2 interfaces to a postscript

printer and uses the Courier font. Line 3 interfaces to the same postscript printer
except it prints two pages side by side in landscape mode using the Times-Roman
font. It is useful for producing program listings.

$lpt "spool su"

$laser spool Jist "f=0 p=8 +p” limp 30

$laseri spool Jist ,f f=4 c=2 p=6 +1 +p” /Imp 30

In the above example, spool Jist is a shell file which interfaces with the Postscript

laser printer, as shown below:

setvar = si [l]5:/tmp/ps.tmp.#n#c
Ips #* +pc >#sl
spool nee su #sl >$null
Fill #1

The keyword "nee" indicates that the spooler associated with the NEC laser printer

is to be used (see the SPOOL command). See the LPS utility documentation for
details about PostScript Laser printers.

If a user then executes the following command:

cp report $Iaser

cp programs $laserl

the following command will be executed in the background, after the text is fully
written and die device closed, or no data is written for more than 30 seconds:

spool list Itmplfile f=0 p=8 +p
or

spooljist Itmplfile f=4 c=2 p=6 +1 +p

where file is replaced with the name of the temporary file created by SPOOLDEV.

SPOOLDEV does not erase the temporary file. It doesn’t know when the
command which it invokes is finished with the file. It is up to the invoked
command to erase it when done.

In the above example, the shell file will erase the temporary file created by
SPOOLDEV. The SPOOLER, if started with proper options, such as:

spooler ”c=cp >$mdm H t=[l]5:/tmp/ &

[SPOOLDEV]

Utilities

SPOOLDEV

will automatically erase the second temporary file after printing it.

The user may specify over-riding timeouts and/or arguments when he names the
spool-device. These are given as extensions to the device name as shown below:

dev_name[.timeout][,arguments]

For example:

copy newfile $laser.5,+d

specifies a 5 second timeout and an additional "+d" argument when the temporary
file is sent to the spool queue.

One final example may prove useful. In a multi-user system, it is sometimes
necessary to set up the parallel printer as,a spooled device, but allow existing
applications that write to $lpt to continue to work. If you place the following lines
in your sys.init./m file:

stty n=$prt >$lpt
spooler d=$prt t=/spool &
spooldev f=/config/spooLinit

and the file /config/spool.init looks like this:

$lpt

then anything written to die device $lpt (formerly the parallel printer) will be
placed on the spool queue, eliminating multi-user printer contention. The printer

port ($lpt) was renamed to $prt so that the system may differentiate between the
physical printer (which SPOOLER wEl write to) and die logical printer which

applications wiE write to.

To run SPOOLDEV, the Timer Administrator must first be started,
timer &

See Also:

LIST SPOOL SPOOLER TIMER

Utilities

[SPOOLDEV]

STTY - Set TTY options

Syntax:

st ty ■ [options]* [>device] [ <device ]

Options:

+echo - Turn on echoing of input (default).

-echo - Turn off echoing.

+efunc - Precede each function and cursor key code with a hex FF.

-efunc - Do not prefix function and cursor keys (default).

•fedit - Perform line editing (default).

-edit - Unbuffered, non-edited input mode.

+etab - Expand TAB into spaces on output (default).

-etab - TABS are not expanded.

+ers - Expand RS (newline) into CR/LF on output (default).

-ers - RS not expanded.

+edei - Expand DEL into BS,SPACE,BS on output (default).

-edel - DEL not expanded.

+fix - Restore all options to their default values.

+FIX - Restore all options and control characters to default values,

•figate - Turn on input gate (default).

-igate - Turn off input gate.

+inapcr - Map CR into RS (newline) on input (default).

-mapcr - CR not mapped.

•fhangup - Allow hangup exceptions to be generated when carrier detect
drops.

-hangup - Disallow hangup exceptions (default).

+hflow - Support flow control with hardware.

-hflow - Support flow control with XON/XQFF (CTL-Q/CTL-S) protocol

(default).

+hold - Freeze tasks when switching to another virtual console.

-hold - Don’t freeze tasks when switching to another console (default).

+iflow - Enable flow control of input.

-iflow - Disable input flow control (default).

+ofiow - Enable flow control of output (default).

-oflow - Disable output flow control.

•flock - Allow only one task at a time to open for write.

-lock - Allow multiple tasks to open for write (default).

+monocurs - Perform cursor handling for the console as if the display adaptor

[STTY]

Utilities

STTY

-monocurs

+noboot

-noboot

+nocolour

-nocolour

+noswitch

-noswitch

+paged

-paged

+poll

-poll

-i-split

-split

ptirae=«

page=w

rows=«

cols=n

break =hh
esc =hh
rub=M
cait=M
eot =hh
ins =hh

del=M

up=M

was a monochrome adaptor. Video cards which allow the use of
color software on monochrome monitors may require this option to
be set.

- Perform cursor handling appropriate to the type of display adaptor
installed. This mode is the default.

- Forbid users from rebooting from keyboard.

- Allow users to reboot from keyboard (default).

- Suppress colour output for black/white monitors which are
connected to colour cards.

- Allow colour output (default).

- Suppress console switching with the control - Alt key
combinations. Programs can still output <Escape> and a console
number from 1 to n to switch consoles under program control.

- Allow console switching with the control - Alt key combinations.

- Turn on paged flag.

- Turn off paged flag.

- Poll line printer (default).

- Printer uses interrupts. See

- Cause the serial port handling within QNX to use only the RTS and
CTS lines to implement hardware flow control. This frees the DTR
and DSR signals for other uses.

- Cause the serial port handling within QNX to use all four hardware
flow control signals ( RTS, CTS, DTR, DSR ). This is the default.

- Set parallel printer poll period. The default value for this setting is
1 millisecond (expressed as 1000 microseconds ). Different
printers will require that this value be adjusted so that a better
output rate can be achieved.

- Define page size (default: 0 - no pagination).

- Set number of rows displayed on the console. On an EGA display
adaptor with the EGA graphics library mounted, a rows=4J option
is supported, allowing a 80 column by 43 line display.

- Set number of columns displayed on the console. If the display
adaptor and mounted graphics library allow, a 132 column mode
could be selected with a co!s=iJ2 option.

- Define input character which causes break (default: Ctrl-C).

- Define input char which escapes to new shell (default: Ctrl-Z).

- Define RUB OUT character (default: 7F hex).

- Define CANCEL (line erase) character (default: Ctrl-X).

- Define character which causes EOF (default: Ctrl-D).

- Define INSERT character (default: Ins on console, Ctrl-N on
terminal).

- Define DELETE character (default: Del on console, Ctrl-K on
terminal).

- Define character which recalls previous line (default: up-arrow on
console, Ctrl-U on terminal).

Utilities

[STTY]

STTY

down=M
left =hh
right =hh

type=n

ioport =hh -

bmd-rate -
par =parity -
stop =/2

bits=a

inton=n

intoff=n

intpri=«

intcp=^rc,^

m=name

Define character which recalls next line (default: down-arrow on
console, LF on terminal).

Define character which moves cursor left (default: left-arrow on
console, BS on terminal).

Define character which moves cursor right (default: right-arrow on
console, none on terminal).

Set console type.

1 - fast colour (don’t wait for retrace)

2 - colour

3 - monochrome

Define the I/O port of device controller or memory segment for
console display.

Define baud rate (default: 1200).

Define parity (odd, even, none, space, mark) (default: none).

Define number of stop bits (default: 1).

Number of data bits (default: 8).

Enable interrupt n (2..15).

Disable interrupt n.

Define which interrupt has the highest priority.

- Copy interrupt vector src to vector dst. This option is used to
allow previously unused interrupt vectors to be set to point to
existing interrupt handlers. For example, to allow interrupt 5 on an
AT to be used for a serial port (as are interrupts 3 and 4 ) the
following would be used:

stty Intcp=4 ? 5

Change name of device ("$" optional).

stty baud=9600 par=even stop=l bits=8 >$mdm
stty -f-oflow +ers -edel -igate -{-poll >[7]$ipt
stty page=24 >$con
stty <$mdm

STTY allows the characteristics of a device to be modified. The features which are
supported by the QNX device drivers can be enabled or disabled to better support a
particular device or terminal. Device dependent parameters such as baud rate and
transmit parity can also be altered with STTY. If no arguments are given, then
STTY will display the current options which apply to die specified input device as
shown in the last example.

[STTY]

Utilities

STFTY

Line editing features can be changed to please the user. For example, the back-
arrow key is used on the IBM keyboard as a RUBOUT character. If an ASCII
terminal is connected to the system, the Backspace key or some other key may be
more appropriate (note that any character but ASCII DEL will not "erase" input
characters from the display). Similarly, the CANCEL key may be defined as a key
which clears a line on a particular terminal.

The newline character which is used by the QNX operating system is an ASCII
Record Separator (RS, hex IE). When CR is typed on a terminal, it will normally
be mapped into a RS (+mapcr). On output, RS is normally expanded into CR/LF
(-fers). The RS character is used within files to separate lines (records) and is
referenced in "C" programs as "\n".

The BREAK, ESCAPE, LEFT, RIGHT, UP, DOWN, INSERT, DELETE,
RUBOUT, CANCEL, and EOT characters all have special meaning to the
operating system. The features supported by these characters can be turned off by
setting these fields to zero in the device table. These characters also lose their
meaning if the EDIT option is turned off.

The BREAK key causes an interruption (break) of a running program which results
in the program being terminated if it is not prepared to handle breaks. The
ESCAPE key causes a program to be temporarily suspended, and allows the user to
type in commands to a new SHELL before the suspended program is resumed.

EOT will indicate end-of-file to a program reading from the terminal.

The UP and DOWN keys allow a user to "step" through the input buffer, one line
at a time. UP will go the the previous line, DOWN to the next (in case you have
"over shot" the line you are looking for). The LEFT and RIGHT keys allow you to
move your cursor left and right over a line of text to perform line editing.

RUBOUT will erase the last character on the line. CANCEL will erase the entire
line. The INSERT character toggles insert mode for the line currently being
entered. Further characters will be inserted before the character at the cursor until
INSERT is again detected. The DELETE character will delete the character at the
cursor.

When the EDIT option is turned off, the operating system stops supporting line
editing and all typed characters are passed directly to user programs without delay.
The following options and special characters are only valid when EDIT is on:

Options

igate

Special Characters

esc

eot

left

rubout

ins

right

cancel

break

down

Utilities

[STTY]

STTY

Input flow control (iflow) is only supported when both EDIT and ECHO are
disabled (such as in TALK).

IOPORT is the I/O address of the control port(s) which .are used by die operating

system to communicate with a device. Asynchronous terminals and parallel
printers use this field. In the case of console displays, this field is the segment of
the display memory.

The default type for a colour card is TYPE=2 which will cause QNX to wait for
horizontal retrace before writing characters to the screen. This eliminates "flash"
on the screen for some colour cards. Specifying TYPE=1 for colour consoles will
stop QNX from waiting for horizontal retrace. This will result in much faster
display updates, especially in the editor, for cards which do not have the flash
problem. TYPE=3 is used for monochrome cards. TYPE=0 means that no monitor
is installed.

INTON allows a hardware interrupt to be recognized by the operating system (an
interrupt handler must be available to service the request). INTOFF disables the
interrupt.

See Also:

MOUNT

NACC

[STTY]

Utilities

STYPE - Type arguments on the terminal (no CR/LF)

Syntax:

stype [arguments]*

Examples:

stype Compiling...

Description:

STYPE will echo its arguments to the terminal. STYPE may be used within
command files to display progress information. No trailing CR/LF is added, so
many consecutive STYPE commands will all print on the same line. Use TYPE to
finish with a CR/LF.

STYPE is a local command which is implemented by the SHELL and therefore
does not require a command to be loaded from disk. A side effect of having the
SHELL implement the command is that output cannot be redirected.

See Also:

ECHO .

TYPE

Utilities

[STYPE]

TBACKUP

TBACKUP - Archive files to QIC tape(s) (QIC02 controllers)

Syntax;

tbackup COnfig c =dma_channel i=ioport u=a\e\i
tbackup INit ["v=volume_name"]

tbackup Files [archjdir] [+summary] [+[-verbose]

tbackup NAme

tbackup SAve save_spec* [-fall] [-clr] [l=levels] [options]*

tbackup REstore [disk_dir[,arch_dir]] [-create] [options]* [+Newer] [+01der]

tbackup [drive] VErify [disk_dir[,archjiir]] [options]*

tbackup [drive] TEst (** some QIC02 controllers only **)

save_spec: disk_dir[,arch_dir] x=indexJile filename[,arch_dir]

options: +pause -verbose -ftension -flist-only +640k +|-hog +old
pf-Wfile_pattern pd =[]dir_pattern pp =[]path_pattern
-fbefore d -dd-mm-yy i=hh:mm:ss (Use digits)

+Force (allow use of non-floppy disks)

%-group m -member
h=number_64k_segments_to_hog
terror Jile

"v-volume jiame" (Use quotes if name contains spaces)

The TBACKUP command is used to archive files to one or more QIC tapes. This
command will allow a single backup to span multiple tapes, so that files larger than
the tape media may also be saved to tape. Each time a file is saved it is appended to
the end of the archive which may span many tapes. Earlier versions of the same
file will NOT be overwritten. You may restore any version of a file on the archive.

When performing a backup that spans tapes, TBACKUP will prompt for new tapes
as required. The CRON utility should also be investigated, as CRON can cause
tape backups to automatically occur overnight.

Utilities

[TBACKUP]

TBACKUP

There are many options for this command and to properly use it, the Floppy and
Tape Backup technical note at the back of this manual should be read.

See Also:

BACKUP CRON FBACKUP
Floppy and Tape Backup Technical Note

[TBACKUP]

Utilities

TCAP - Manage terminal capability database

Syntax:

tcap append tcapjile [name] [f-database]
tcap copy name newjiame [f =database]
tcap create [ numjiodes ] [f-database]
tcap delete name [occurrence] [f -database]
tcap define name [f-database]
tcap keys [f -database]
tcap list [f -database]
tcap query [f -database]

tcap set name [f-database]

tset name

Options:

tcapjile - TCAP database to append from,
f -database - TCAP database to use

(default: /config/tcap.dbase).
name - Entry within the database.

newjiame - Name of a new entry.
numjiodes - Maximum number of nodes in network
(omit for non-networked QNX).
occurrence - Which of several entries with the
same name to use.

Examples:

tcap set qex

tset qnxs

tcap define vtlOO

tcap copy qnxs vt52

tcap append old.tcap.dbase vtlOO

Description:

[TCAP]

Utilities

TCAP

TCAP is a data base describing the capabilities of terminals connected to QNX. It
is used by commands such as ED and MAIL to determine the escape sequences
required to move the cursor, turn on attributes, recognize function keys etc...

The TCAP database file contains information about every terminal on every node
in the network. A terminal type need only be SET once into the database. Once set,
all full-screen applications should work properly on that terminal.

The data base is kept in a file called ’tcap.dbase’ under the directory ’config’.

/config/tcap.dbase

This file is maintained by the TCAP command. A different database may be
selected by using the f= option. This is often useful when testing a new terminal
entry before committing it to the system TCAP database.

Three of the standard entries in the tcap.dbase file begin with the letters "QNX".
They should be used in the following circumstances:

qnx - For the consoles. If you are on the console and your tcap entry is not set, it
will default to qnx. This setting lets the term() functions use high speed
video calls. The QNX terminal characteristics are fully supported.

Remote execution when invoked from the console, will behave like a qnxt
setting even if the console is set to qnx. This is because high speed video
calls only work on a local machine.

qnxs -This entry is used when a user is communicating to a QNX system using

TALK. Since TALK does not send an FF character to precede function key
codes, it does not fully support the QNX terminal characteristics. With this
tcap setting, the term_key() library will insert an FF when the 4-efuncs op¬
tion is enabled. In this way, programs like ED which use the FF character to
distinguish between data and commands will be able to work. Any data
which has the value of a function key will be taken as a command, due to
the automatic insertion of the FF. The major disadvantage to using qnxs is
that there is no means to enter foreign language characters.

This setting will throw away FF’s if they come in because term_key() is
generating them on its own based on the value of the data received, so if you
have a QNX compatible terminal you should avoid using this mode.

qnxt - Used when communicating with a QNX compatible terminal to another
QNX system through a serial line. This setting assumes that the terminal
fully supports the QNX terminal characteristics (including colour). To take
full advantage of QTALK and QTERM, this setting should be used. There
are other terminals on the market which also support this tcap setting.

Utilities

[TCAP]

TCAP

Setting your tcap entry to qnxs or qnxt will never go through high speed video
calls when using the term() functions.

APPEND

This command will append the terminal entries in a specified data file to the data
file in ’/config/tcap.dbase’. For example, assume that you have just received a tcap
data file from a friend which contains several terminal definitions which you wish
to use. The APPEND command may be used to append the new definitions to the
end of your tcap data file. This might result in multiple definitions for the same
terminal. You can remove a multiple definition using the DELETE command. If a
name is specified, then only that entry will be copied over.

The APPEND command can also be used to change the number of node-id’s
supported. For example, to change the number of node ids to 12 you might enter
the following sequence of commands.

chattr n=oldtcap.dfoase /config/tcap.dbase
tcap create 12

tcap append /config/oldtcap.dbase

COPY

This command will make a copy of an existing terminal entry. This is useful when
defining a new terminal which is substantially the same as an existing terminal.
After the copy you would use the DEFINE command to make and changes to the
new entry.

CREATE

This command will create the file ’/config/tcap.dbase’. The numjiodes parameter
is used by the networking version of QNX. It should be set to the node-id of the
highest node in the network. A value of zero may be used for non-networked
versions of QNX, or the field can be omitted entirely.

DEFINE

This command is used to define new terminal definitions and modify existing
definitions. The terminal capabilities are entered into several full screen menus.
Each menu is responsible for one particular aspect of a terminal definition. The
editor documentation contains a section on terminals which may give further
insight into its operation.

[TCAP]

Utilities

TCAP

When creating a new terminal definition, menu 1 should be completed on another
terminal which has an existing TCAP definition (like the console). After saving it
away you may wish to complete the definition on the terminal being defined. This
will allow you to type in the special keys on the terminal rather than having to
enter a series of escape sequences. The TCAP program uses the direct cursor
information in menu 1 to position the menu on the screen. It makes use of NO
other terminal capability.

Upon entering each menu you will be prompted for an action. Enter the first letter
of a command to select it.

CHANGE

PREY

ABORT

SAVE

Enter the current menu for changes

Goto the next menu

Goto the previous menu

Exit TCAP without saving any changes

Exit TCAP and save any changes

The CHANGE command will move you cursor to the first menu field. When
positioned at the start of a menu field you may enter a

carriage return
space
the letter E
the letter R
the character \

goto next field

goto previous field

erase current field

return to the menu

take the next character as data

Any other character will be taken as data. The current field will be
erased and the typed character entered as data into the field. Each
successive character will be entered as data until

1. The maximum field length is exceeded.

2. A carriage return which was not preceded by a
backslash (\) is entered.

The cursor will then be positioned at the next field. If the field prompt ends with a
colon (:) then ASCII input is expected. If the field prompt ends with an equal sign
(=) then numeric input is expected. All numeric input is assumed to be decimal.

The menu for box characters and input keys will be initialized to default values
when you create a new terminal entry. These may be changed to more closely
accommodate your terminal. For the input key escape sequences you should use
particular care to avoid identical escape sequences for more than one key. For
example, the default value for the Page Up key is a Ctrl-b. If your terminal
generated a Ctrl-b as a leadin for its functions keys you will have to change the
default for Page Up to something else. As another example, some terminals return

Utilities

[TCAP]

TCAP

a TAB character for their right arrow key. In this case you will have to redefine the
TAB key to be something like an ESC t or you will be unable to enter tabs.

DEFAULT KEY DEFINITIONS

Alternate - ESC a

Up Arrow
Down Arrow
Left Arrow
Right Arrow

Ctrlu

Ctrlj or Linefeed
Ctrlh or Backspace
Ctrl r

Home - ESC h

End - ESC e

PageUp - Ctrl a

Page Down - Ctrl b

Insert

Delete

Rubout

Erase line

Select

Cancel

Help

Show

Tab

Tab to begin
Tab to end

Ctrln

Ctrlk

Delete or Rubout
Ctrlx
ESC CR
ESC -
ESC?

ESCs

Ctrli or Tab
ESC TAB b
ESC TAB e

Alternate - ESC a

FI to F10 - ESC 1 to ESC 0

Fllto F20 - ESC! to ESC)

NOTE; The following arc die translations which are done for the function keys:

TCAP entry

Actual term keyO value

FI toFlO

= FI to

F10

Fll toF20

= CNTL FI to

CNTL F10

Alternate FI toFlO

= SHIFT FI to

SHIFT F10

Alternate Fll toF20

= ALT FI to

ALT F10

DELETE

[TCAP]

Utilities

TCAP

This command will delete the terminal entry specified. The terminal name
specified must be in the data base. If the occurrence option is specified, then the
n’th occurrence of a terminal entry will be deleted. This option is useful when
multiple occurrences of a single terminal exist within the teap data file.

KEYS

This command will display the escape sequence for the special keys. These may
be generated automatically by keys on the keyboard or entered manually as multi¬
character sequences.

LIST

This command will list the names of all terminals in the data base.

QUERY

This command will list the name of your active terminal entry. It should match the
physical terminal which you are connected to.

SIT ' ‘ ; '

This command will change your active terminal entry to the terminal specified.
The terminal name specified must be in the data base.

The TSET compand is provided to allow non super-users to set terminal types. It
is functionally Equivalent to the TCAP SET command, but does not require the
user to be a super-user.

See Also:

TSET

Utilities

[TCAP]

TIMER - Implement timing facility in QNX

Syntax:

timer [no_account__entries] &

Options:

no_account_entries - maximum number of queued timer requests.
Default is 10.

Description:

TIMER implements a timing facility in QNX. It is required by many utilities and

3rd party applications. Unless you are absolutely certain that you don’t need it,

you should be running TIMER. TIMER is usually started from the sys.init at boot

time, and always left running.

If you ever do need to terminate TIMER, use the SLAY command:
slay timer

See Also:

CLRHOUSE

CRON

LOCKER

QCP

SLEEP

SLICE

SPOOLDEV

[TIMER]

Utilities

TSET - Set terminal type

Syntax:

tset [terminal_type]

Description:

TSET allows the user to define query or define which type of terminal is in use for
the current $tty device. For example, if a user was logged into a QNX machine
from a vtlOO terminal, the command:

tset vtlOO

would allow QNX to recognize the terminal type so that QNX full screen applica¬
tions would be able to operate correctly. This example assumes that a vtlOO
terminal type is defined in the file /config/tcap.dbase.

Typing the command:

tset

would cause the TSET command to display what the currently defined terminal
type is.

Note that the TCAP command could also perform this operation, but the user of
the TCAP command must usually be a super-user because the TCAP command
also allows the contents of the /config/tcap.dbase file to be modified. The TSET
command is usable by a non-super user because it does not modify the
/config/tcap.dbase file.

See Also:

TCAP

Utilities

[TSET]

TSK - Display task information

tsk [f={cmoprstJ] [i=tty] [n=userid\

tsk code [p -program}
tsk info
tsk mem tid ...
tsk names

tsk size [i-tty] [u-userid] [p=program]

tsk ports
tsk tree [+tid]

tsk users [t -tty] [u -userid} [p -program]

tsk vcs

tsk who tid ...

options: +qnx -header +physical n -node s =sorfield

-header

+physical

+qnx

f={cmoprst}

n=node

s-sortfield

t -tty
u -userid
p=prograrn

tid

Don’t include a header.

Display memory as 24 bit addresses. Selectors in protected
mode are mapped to real physical memory addresses.

Use the QNX line drawing set when the tree option is used.
This is the default on the console but must be requested on a
terminal.

Select a set of fields of information to be displayed. Each

letter included represents a field.

Obtain information from the indicated node rather than the
local node.

Sort the lines based upon information in the indicated field.
Each field is a column separated by blanks. The fields are
numbered as s=l (first), s=2 (second),...

Only display tasks associated with the indicated tty.

Only display tasks associated with the indicated userid.

Only display information associated with the program task.
Display information on the indicated task.

Utilities

[TSK]

TSK

Examples:

tsk

tsk t=3
tsk u=bill

tsk mem
tsk mein 30c
tsk Info
tsk tree n=7

tsk vcs

Description:

The TSK command allows the user to obtain a "snapshot" of the tasks which are
currently in existence. If present, the keyword after the command allows you to
select different types of information and different views of the information
displayed. You need only type the first two characters of a keyword.

There are several options common to all forms of the command. The n -node

option obtains information on another node in the network. The default is to obtain
information on the current node. The s =sorfield option allows you to sort the
displayed lines of information based upon a field. You could sort by tty, task id,
state, code size ... The -f physical option maps 286/386 protected mode selectors
into real 24 bit memory addresses.

TSK

When invoked without a keyword TSK will list the name of all tasks which are
currently active. The task-id (tid), state, priority, user-number, and associated tty
are displayed for each task as well as the father-son relationship of the tasks.
Priorities range from 1 to 15 with 1 being the highest. The task flags field contains
letters to indicate the following:

A - Administrator.

C - Concurrent execution.

D- Doomed.

E - Escaped shell.

H- To be Held.

L ■» Locked in memory.

N - New task entry in the process of being created.

P - Privileged.

The f={cmoprst} allows you to select which type of information you wish
displayed. Each letter specified includes a field of information as follows.

- Display a brief summary of all the tasks in the system.

- Display a listing of all tasks associated with tty 3.

- Display a listing of all tasks associated with userid bill.
- Display the free memory in the system.

- Display any extra segments used by task (Tid) 30c.

- Display system configuration information.

- Display task tree on node 7.

- Display virtual circuits to other nodes.

[TSK]

Utilities

TSK

c -

o -

P -

r -
s -

t -
u -

Number of programs sharing this code segment and its Code flags.
Memory (code/data) used.

Ownership (group/member).

Program name and task id.

Relationships (father/brother/son).

State Information (state/blockedon/priority/fiags).

Tty.

Userid.

eg: tsk f=pu (display program names and userids)

You may wish to create a shell command to invoke TSK with your favorite
options.

TSK CODE

Display information on each code segment running in the system. The programs
name and the number of links (programs sharing the code segment) to the program
are displayed. The flags field contains letters to indicate the following:

F - Uses Floating point (8087).
H- Loaded in high memory.

L - Locked in memory.

O- Change Owner.

P - Privileged.

R- Remote creates ok.

S - Shareable.

TSK INFO

Displays information on QNX itself. This includes the version number and the
date the operating system was created. Maximums for a number of items are
displayed including number of tasks and files. The flags field contains letters to
indicate the following:

D - Memory below 1 Meg reserved for DOS.

F - 8087 installed (float).

L- Large file system supported.

M- Memory manager task running.

P - Password protection enabled.

R - Remote creates allowed for non super-users.

S - Automatic sharing of code segments enabled.

TSK MEM

Display information on extra segment memory usage. If no arguments are

Utilities

[TSK]

TSK

provided then the system memory free list is displayed. If you provide one or
more task id’s then the extra memory segments allocated by those tasks is
displayed.

TSK NAMES

Display registered names in the system. Both names registered on the global name
server and names registered on the local machine are listed.

TSK SIZE

Display information similar to that shown when TSK is invoked without a
keyword, only replace the father/brother/son information with the tasks sizes.

TSK PORTS

Display which ports are in use and the tasks which have attached to them.

TSK TREE

Display a graph showing the relationship of tasks running in the system. The tty is
displayed at the end of each line. The +tid option will include the task id with the
name of each task in the displayed graph.. You may select a subset of tasks to
match using the i-tty or u -userid options. On the console the line drawing
characters are used while on a terminal +’s, I’s and -’s are used. If your terminal
supports the console line drawing character set you can force it to be used with the
+qnx option.

TSK USERS

TSK will list the name of all tasks which are currently active. The task-id (tid),
userid, state, priority, user-number, and associated tty are displayed for each task.

TSK VCS

Display virtual circuits existing between this node and other nodes in the network.
The display shows each local task id and program which has a virtual circuit to
another node and task id. The virtual id’s and the size of the virtual circuit is also
displayed. You can obtain more information on the task at the far end of the
virtual circuit using the WHO subcommand and providing the local vid as an
argument.

TSK WHO

Display the tty, program name and userid running the indicated task. If you type in
a virtual id (vid) then information on the remote real task is displayed.

[TSK]

Utilities

TYPE - Type arguments

Syntax:

type

type text

• This is a local shell command •

Description:

The arguments following the command are displayed on the terminal, followed by
a carriage return. This is often used within command files to display progress
messages.

See Also:

ECHO

[TYPE]

Utilities

TZSET - Display or set timezone offset

tzset [[+-]hour[:min]]

hour - 0-12
min - 0-59

Examples:

tzset
tzset +5
tzset -3:30

If no arguments are given, the TZSET command allows the user to display the
timezone offset on their terminal. The timezone offset is specified as a number of
hours and minutes, plus or minus, from Greenwich Mean Time (GMT). This offset
is used to adjust the internal time, which is maintained in GMT, to local time for
display purposes.

When changing the timezone, the hour is entered first (optionally preceeded by a
plus or minus; plus is assumed). The hour may be followed by a colon (:) and a

number of minutes (which must be a multiple of 15) for die few places in the world

which are in a timezone that is not on the hour (Newfoundland, Canada for
example).'

If you are in a location which periodically adjusts its clocks (for example, Daylight
Savings Time), simply adjust the timezone offset given to TZSET to maintain the
correct local time.

See Also:

CLOCK DATE ' RTC

Utilities

[TZSET]

UNPACK - Unpack a packed file

Syntax:

unpack file* [options]*

unpack <infile >outfile [options]*

Options:

■ 4 -display - Force output to the screen.

-remove - Suppress the removal of input files.

^verbose - Display status messages.

-time - Retain original file time. Set to current time by default.

Examples:

unpack - Unpack all packed files

in current directory
unpack <packed_text >text

Description:

UNPACK expands packed files into exact duplicates of the original. UNPACK
operates on files which have been created with the PACK utility.

When the first form of UNPACK is used each file will be replaced by a file with
the same name and the jl removed. The packed file will by default be removed.
You can suppress the removal by specifying the -remove option.

When the second form of UNPACK is used it will read from the standard input and
write to the standard output. In this case the input file will never be removed and
you have control over the name of the output file. The -fdisplay will force all
output to the screen. The input packed files will not be removed. If more than one
file is specified they will be appended together. If you were on the console the
following two command would be the same:

unpack file +display

Utilities

[UNPACK]

UNPACK

This option is typically used to quickly examine the contents of a packed file.
If the +verbose option is specified each file will be printed as it is unpacked.

See Also:

PACK

[UNPACK]

Utilities

W C - Word count

Syntax:

wc | file]* [-chars] [-lines] [-words] [-verbose]

Options:

file - Name of a file to count. If omitted
the standard input is used.

-chars - Don’t display the number of characters.

-lines - Don’t display the number of lines.

-words - Don’t display the number of words.

-verbose - Don’t display the file name and omit
descriptive text.

Examples:

wc teste

wc *.c «w

wc inventory mailingjist -c -v

Description:

WC will count the total number of characters, lines and words in each of the given
files. The number of lines and words is only meaningful for text files. A word is a
maximal string of characters delimited by spaces, tabs or newlines.

If more than one filename is given, then WC will also report the total number of
characters, lines and words in all the files.

See Also:

SIZE

[WC]

Utilities

WHO - Who is logged-in to the system

Syntax:

who [ami I net I node*] [options]*

Options:

am i - Display who you are.

net - Display all users in the network.

node - Display all users on this node.

-header - Suppress column header.

-[-system - Display system owned tasks.

-verbose - Display only owner, tty and task name.

Examples:

who

who am i

who net +§

who 3
who 3 5 7

Description:

The WHO command will display the users which are logged on to the system. The
output will be of the form.

Node User TTY Idle-Time Sign-On-Time Flags Command

4 opr 0 0:00:49 Nov-23 5:21 pm — sh

& dtdodge 4 0:02:45 Nov-23 5:06 pm sh

If invoked with no arguments, WHO will display all users logged-in to your
machine. The am i option is useful to find out who is logged on to an unoccupied
machine or a second window on the console. The net option will list all users
logged on to all machines in the network.

The NODE field will only be displayed when running the network version of

QNX.

Utilities

[WHO]

WHO

A field of dashes (— --) for the time indicates that someone forgot to set the date in
the system.

The idle time field displays how long it has been since a character was received by
that particular tty. This field is particularly useful for the detection of users who
have been idle long enough that they should be logged off.

The flags field indicates that a message is waiting to be printed on that users

console.

A - An appointment was changed

B - An APB (all points bulletin)

C - Chat request
M - A MAIL WAITING message

See Also:

NET

[WHO]

Utilities

ws - Walk directory Structure executing a command

Syntax:

ws [directory ["command... 11 ]] [options]*

Options:

dc=delete_char - This character when present in command will delete the
previous character of the expanded string, (default is a
backquote)

pc =path_char - This character when present in command will be replaced

by the current pathname. If the path_char is followed by a
question mark, then the two character sequence will be
replaced with input prompted for from the standard input.

If the path_char is followed by another path_char then
only the filename and not a complete pathname will be
replaced. This is sometimes useful when +replace is NOT
specified but you still want the relative name, (default is an
at-sign @)

d -date - Match only those files which have changed since this date.

Date is of the form dd-mm-yy. (default is 01-Jan-80)

t =time - Match only those files which have changed since this time

on the given date. Time is in the 24 hour format hh:mm:ss.
(default is 0:0:0)

1 ^levels - Specifies how many levels down from the indicated

directory will be searched. The default is 1=1 and will
cause only files at the current level to be searched, not files
under subdirectories.

g =group - Indicates that only files whose group number matches

group will be selected.

m -member - Indicates that only files whose group member number

matches member will be selected.

p =[ h ]pattern - Indicates that only files whose name match this pattern

will be selected. Up to ten p= options are allowed, in
which case files which match ANY of these patterns will
be copied. Also, if the pattern is preceded by an up- arrow
( A ), then files which match this pattern will NOT be
selected.

+abort - If a command returns a non-zero status then WS will abort.

+before - Changes the meaning of the time and date options to mean

Utilities

[WS]

4-directory

4-error

blocked

-locked

+modified

-modified

4-query

4-relative

-verbose

Examples:

before. The default is now or after.

Selects directories rather than files.

If a command returns a non-zero status, a prompt to
continue will be displayed, (default is to ignore returned
status)

Match only files which are BUSY.

Match only files which are not BUSY.

Match only files which have been modified and not
backed up using the BACKUP command.

Match only files which have been not been modified.
Before executing each command a prompt will be issued
requesting permission to execute. If option verbose is set
(default) then the entire command line will be prompted,
otherwise only the selected pathname is printed. A single
5 y 5 will execute while anything else will skip to the next
pathname.

The WS command will usually generate complete
pathnames from the indicated directory. This option will
cause WS to do a CD command when it moves to each
new directory and the pathname will be the simple
filename at this directory.

Suppress the printing of each command before it is
executed.

ws "frel - Remove all files at current directory,

ws /user/bill "frel 1=20

- Remove all files owned by bill,
ws /user/bill "drel 1=20 +d

- Remove all directories owned by bill,

ws "chattr n=@? p=*data*

- Change the name of all files containing the string "data" to
a new name which will be prompted for.

ws "ed p=*.c d=3/l/83

- Edit all C programs which were changed on Ian 3,1983.
ws 2tl "type -v p=xyz 1=12

- Search all of disk 2 looking for the file xyz. If found, print
its complete pathname.

WS is a utility which increases the power and scope of existing QNX commands. It
is a very powerful command and should be carefully studied. You may rarely need
it, but when you do, it will be of untold value!

[WS]

Utilities

The simplest form of the command is:

ws "command arguments"

which will execute the command in double quotes on each file in the current
directory. The double quotes are necessary. Any occurrence of the AT-SIGN
character (@) will be replaced by the current filename. For example:

ws ’’type @" - Type name of each file in current directory

ws ”frel - Release each file in current directory

A number of options may follow the command. The two most common being
•fquery and -verbose. The query option will prompt you for each possible execu¬
tion of the command. A single "y" will execute the command, anything else will
skip execution and proceed to the next. The -verbose option suppresses the
printing of each command before execution.

WS will not normally descend to subdirectories in the current directory. This can
be overridden by specifying the number of directories to descend using the \~levels
option. The following example will release all files under the directory "Aiser/biH"
including all subdirectories. The directories are then removed. These two
commands have effectively released all a users’ files, perhaps in preparation of
removing his user id.

ws /user/joe ”frel 1=100 - Release all files

ws /user/joe ”drel +d 1=100 - Release directories

Note that in this case a particular directory was specified and in the second
example the +directory option matched directories, NOT files.

The time and date options allow the selection of files based upon their last change.
The default will typically select all files. The following command would
recompile all C source files which were changed today (read up on the MAKE
command for a better method).

ws "ce-c @" p=*.c d= 1=5

Note that a null string for the date defaults to today.

The p =[ h ]pattern option follows the same syntax as the BACKUP command and it
should be referred to for wildcard character definitions.

The AT-SIGN prompt (@?) is provided to increase the flexibility of the WS
command. There is no limit (within reason) to the number of @? prompts you may
have on a command line. For example

Utilities

[WS]

ws "type

will prompt for each of the five arguments. Note that the @ does not need to be
delimited by spaces. This is a silly example in that it will select each file in the
current directory but does not expand it on the command line. The more realistic
example below allows the super user to interactively set the ownership on each
user directory

ws /user "chattr @ o=@?" +q

The + relative option will cause WS to issue a CD command before entering each
subdirectory. The pathnames expanded by the AT-sign (@) will contain the last
component of the full pathname. This can best be understood with an example.

ws hi "type 1=10 - Type complete pathnames.

and

ws hi "type +r 1=10 - Type simple file names.

All examples above have contained a command and some have contained an
overriding directory as their first argument.

If neither is specified then WS will operate on the current directory and prompt
for command lines from the standard input. Each input line will be executed on all
selected files and the user will then be prompted for another command. An end-of-
file (Ctrl-D) will terminate the command.

If a directory is specified then the syntax requires you to enter a command. If the
command is an empty string then you will be prompted as above.

ws ’ Prompt for commands and operate

on current directory.

ws /user/bill "" - Prompt and operate on /user/bill

WS could be used as a filter in which it was piped a series of commands. The
following simple example assumes that the file my_cmds contains a list of
commands you wish executed on all files ending in M .c" at the current directory.

ws p=*.c <my_cmds

See Also:

BACKUP EO MAKE

[WS]

Utilities

XLAT - Translate Characters

Syntax:

xlat xfile [+raw] [+wildcard] [<input JUe] [>output Jtle ]

Options:

+raw - Turn off output character mappings (ERS, EDEL,
ETAB). This only affects output to a device.

^wildcard - Allows the use of the *?’ charcater to match any single
char. This is useful for removing escape sequences from
log files.

xlat qume.xlat </expl/inform >$lpt

Description:

XLAT will translate single characters or multi-character sequences found in
input Jile based on the translations specified in xfile.

The translation file specified by xfile consists of one or more translate entries with
optional comments. A translate entry has the form:

input_seq output_seq [aU_output_seq]

where each translate entry is on a separate line, inputjseq, outputjseq and
altj>utput_seq have the form:

char [,char]*

char may be specified as an actual character, two hex digits, or a carat ( A ) followed
by an actual character. The last case will result in a control character if (and only
if) the actual character is alphabetic (a-z or A-Z), else the actual character will be
used (this can be useful for entering a comma (,) or carat ( A ), otherwise the hex
value could be given). A comma (,) is used to separate characters and white space
(spaces or tabs) is used to separate sequences.

Utilities

[XLAT]

XLAT

If the alt_output_seq is given (it normally is not) then input jeq will toggle
between the two possible output sequences.

The following xlat table will convert all record separators, tabs and runs of two
spaces to a single space. Because only one pass is made through the translation
table, this will not reduce all "white space" to a single space.

le 20

09 20

20 9 20 20

This table will translate some control characters into their ASCII name with
alternates for tab and rubout.

00 < ? N,U,L,>

04 <,E,G ? T,>

07 < 9 B ? E 9 L 9 >

08 < 9 B,S,>

09 < 9 H,T,> <,T,A,B)>

0a < ? LjF ? >

0c <,F,F,>

Od <,C,R ? >

11 <,D,C,1>>

13 <,D,C ? 3,>

lb < 5 E 9 SjC,>
le < 5 R,S 5 >

7f < ? D ? E,L> <,R,U,B)>

You may wish to create a number of table to convert

upper case --> lower case

ascii »-> ebcdic

QNX escape daisy wheel printer

sequences escape sequences

[XLAT]

Utilities

ZAP - Zap damaged files out of existence

Syntax:

zap file

Examples:

zap junk

zap /user/bill/junk

Description:

ONLY USE THIS COMMAND TO RELEASE DAMAGED FILES.

ZAP should be used when a file is known to contain bad disk blocks, or if a file has

been left in an inconsistent state (FILE BUSY) due to a system crash while a file

was being written.

ZAP releases files by clearing the directory entry for that file. The disk blocks used
by that file are NOT reclaimed. Repeated use of ZAP will therefore reduce the total
number of disk blocks available to the user. These can be reclaimed by running the
CHKFSYS utility when the system is idle.

Normally, a user should use the FREL, DREL, RM or RMDIR commands to
release files or directories.

See Also:

CHATTR DREL RMDIR

CHKFSYS FREL RM

Utilities

[ZAP]

ED Manual Page

1. INTRODUCTION i

2. TUTORIAL GUIDE 3

2.1 Getting Started 3

2.1.1 The Status Line 5

2.1.2 The Command Line 7

2.1.3 Text Area g

2.2 Appending New Text (FI key) g

2.3 Appending or Inserting Lines (F1/F2 keys) 9

2.4 Using the Del and Back-arrow keys 9

2.5 Inserting text using the Ins key 10

2.6 Other Cursor keys which Simplify Editing 10

2.7 Saving your Text 11

2.8 Exercise 2 11

2.9 More on the FI and F2 keys 12

2.10 Deleting Lines (F3 key) 13

2.11 Filling Lines (F4 key) 14

2.12 Centering Lines (Ctrl-F4 key) 14

2.13 Splitting and Joining Lines (F5/F6 keys) 14

2.14 Tagging Blocks of Text (F7/F8 keys) 15

2.14.1 Line Tagging 15

2.14.2 Block Tagging 16

2.14.3 Insert Mode and Block Move and Copy 18

2.14.4 Re-setting the Last Tagged Lines or Block 18

2.15 Re-executing Commands (F9/F10 keys) lg

2.16 Zooming Your Text 19

2.17 Tabs 19

2.18 Composed Characters 20

2.19 Line Drawing Characters 20

2.20 Margins 20

2.20.1 Moving Your Margins (Shift FI to F6) 20

2.20.2 Auto Fill and Your Right Margin 20

2.20.3 Auto Justify 21

2.20.4 Indenting and Your Left Margin 21

2.21 Line Flags 22

2.21.1 Overstrike Flag (Alt-o) 22

2.21.2 Continuation Flag (Alt-c) 22

2.21.3 Paragraph Flag (Alt-p) 22

2.22 Some Simple Editor Commands. 23

2.23 Learn Mode 23

2.24

Absolute Line Positioning

2.25

Simple Pattern Matching

2.26

File I/O Commands

2.27

The View Command

2.28

Executing System Commands

2.29

Epilogue

. 29

Using Ed on a Terminal

• 31

3.1

Setting Your Terminal Type

3.2

Required Terminal Capabilities

3.3

Screen Output

3.4

Keyboard Input

3.5

QNX Compatible Terminals

REFERENCE MANUAL

4.1

The Syntax of Editor Commands

.37

4.1.1

Line Range

4.1.2

Command Specification Character

4.1.3

Right Arguments

4.2

Placing Multiple Commands On A Line

4.3

Special Characters

4.3.1

The Newline Character (hexadecimal IE)

• 41

4.3.2

The Null Character (hexadecimal 00)

4.3.3

The Meta Characters @$&.*[

4.3.4

The Backslash Character \

4.3.5

The Tab Character (hexadecimal 09)

4.3.6

The Command Character (hexadecimal FF)

4.3.7

The Recall Character (hexadecimal FE)

4.3.8

The Keyboard Input Character (hexadecimal FD)

4.3.9

The Macro Disable Character (hexadecimal A3)

4.4

The Condition Register

4.5

Delete Buffers

4.5.1

The Character Delete Buffer

4.5.2

The Line Delete Buffer

4.6

Break Handling

4.7

The Pattern Matcher

4.8

Some Pattern Examples

4.9

Editor Commands

4.10

a - Append After Current Line

4.11

b - Branch

4.12

c - Change Lines

4.13

d - Delete Lines

4.14 e - Edit a New File 53

4.15 f - File Query/Set 54

4.16 g - Global 55

4.17 i - Insert Before Current Line 57

4.18 j - Join Two Lines 58

4.19 k - Kopy Lines 59

4.20 1-Learn 60

4.21 m - Move Lines 61

4.22 o - Option Query/Set 62

4.22.1 oa - Option Anchor 62

4.22.2 ob - Option Blank 62

4.22.3 oc - Option Command 63

4.22.4 od - Option Dual 63

4.22.5 oe - Option Environment 63

4.22.6 of - Option Fill 63

4.22.7 oi - Option Insert 63

4.22.8 oj - Option Justify 63

4.22.9 ol - Option Limit 64

4.22.10 om - Option Meta Characters 64

4.22.11 on - Option Newline 64

4.22.12 os - Option Autosave 64

4.22.13 ot - Option Tabs 64

4.22.14 ow - Option Wrap 64

4.23 p - Print Lines 65

4.24 q - Quit (Leave the Editor) 66

4.25 r - Read a File 67

4.26 s - Substitute Text 68

4.27 t - Translate a Key on Input 70

4.28 u-Until 72

4.29 v - View Screen Options 74

4.29.1 va - Attribute 74

4.29.2 vc - Center Line 75

4.29.3 vf - Full Display of Text and Attributes 75

4.29.4 vl - Left Margin 75

4.29.5 vr - Right Margin 76

4.29.6 vs - Scroll Screen 76

4.29.7 vt - Set tab settings 76

4.29.8 vz - Zoom the size of your screen 76

4.30 w - Write Buffer to a File 78

4.31 x - Execute a File of Editor Commands 79

4.32 y - Yut? 80

4.33 z - Zap 81

4.33.1 zee - Zap Cursor Change 82

iii

4.33.2 zed - Zap Cursor Delete 82

4.33.3 zcD - Zap Cursor Delete Multiple 82

4.33.4 zee - Zap Cursor Erase 82

4.33.5 zef - Zap Cursor Fill 83

4.33.6 zch - Zap Cursor Horizontal 83

4.33.7 zcl - Zap Cursor Lock 84

4.33.8 zep - Zap Cursor Purge 85

4.33.9 zer - Zap Cursor Restore 85

4.33.10 zcR - Zap Cursor Restore Multiple 85

4.33.11 zes - Zap Cursor Save 85

4.33.12 zh - Zap Home 86

4.33.13 zk - Zap Kopy 86

4.33.14 zlc - Zap Line Center 86

4.33.15 zld - Zap Line Delete , 86

4.33.16 zle - Zap Line Erase 87

4.33.17 zlf - Zap Line Fill 87

4.33.18 zlj - Zap Line Join 87

4.33.19 zlo - Zap Line Overstrike ■ 87

4.33.20 zip - Zap Line Paragraph 87

4.33.21 zlc[ - Zap Line Ouerv 88

4.33.22 zlr - Zap Line Restore 88

4.33.23 zlR - Zap Line Restore File 88

4.33.24 zls - Zap Line Save 88

4.33.25 zlt - Zap Line Tag 89

4.33.26 zlu - Zap Line Untag 89

4.33.27 zlw - Zap Line Write 89

4.33.28 zm - Zap Message 89

4.33.29 zp - Zap Purge 89

4.33.30 zq - Zap Query 90

4.33.31 zv - Zap Version 90

5. DEFINING YOUR OWN MACROS 91

5.1 What is a Macro 91

5.2 Multi-line Macros 93

5.3 Macros Containing Branches 93

5.4 Suggestions 95

APPENDIX A - ERROR MESSAGES 97

1. INTRODUCTION

ED is a foil screen editor for both your console and attached terminals. QNX

Software Systems has structured this documentation into several major sections.

1. Tutorial Guide This section consists of a conversational introduction to the

Full Screen Editor. It contains examples which should be
attempted on your PC as you read. It is highly recom¬
mended that all users, regardless of their level of computer
experience read this guide. The first several pages contain a
complete reference to all the defined function and cursor
keys. It will help you correlate the many functions
available. Upon completion of the guide you should be
capable of performing most editing tasks. For most users,
this may be all you need to know about the editor.

2. Using Terminals This section describes how to configure ED for attached

terminals. No configuration is necessary for the console.

3. Reference Manual This section consists of a detailed description of every

command supported by the editor. You will discover that
the defined function and cursor keys are in fact im¬
plemented as one or more of these commands. Anyone
who is going to be using the editor on a regular basis should
read the preliminary sections up to the APPEND command.
The description of the SUBSTITUTE and GLOBAL com¬
mands are also highly recommended. Should you wish to
define your own fonction key operations then it is impera¬
tive that you read and understand ALL sections.

4 . Defining Macros This section has been written as a tutorial guide in the

writing of macros. It should be sufficient to get you started.
However, the best way to learn about macros is to ex¬
periment.

ED 1

ED 2

2. TUTORIAL GUIDE

The full screen editor is a program which allows you to type in text, edit it and
save it away in a file. The editor itself treats your text as a series of lines con¬
sisting of from 0 to 512 characters. It was designed as a program development
editor first and a word processor second.

When operating on text from a file, the editor reads a copy of your file into
memory (we will call this a buffer). Any changes you make to your file copy (the
buffer) will not affect the original file until you issue a write command to save
your buffer. Should you change your mind about saving the particular changes you
have made, you may exit without saving, or you may reread a copy of the original

The maximum number of lines you can edit will depend on how long each line is
and the amount of available memory space. The maximum number of real charac¬
ters in a file that may be edited is on the order of 60,000. Larger files must be split
and if necessary rejoined after editing.

2.1 Getting Started

Assume you want to enter some text and save it away in a file. Making sure that
your commands disk (/cmds) is in one of your drives, enter the command.

The editor will load from disk, clear your screen, then present a screen that should
look like this.

ED 3

status line
command line

text area

The top line of the screen is the status line and provides information about the size
of your file, where in the file you are currently located, and what editing options
you have selected. This line is kept up to date by the editor. You may NOT enter
text into this area.

The second line of the screen is the command line. It is the area where you may
type editor commands which are to be executed. On the monochrome display, a
solid line appears after this line.

The rest of the screen is for text. If your text is longer than or wider than the
screen, then this space represents a window into your text. As you progress, you
will quickly leam how to position your window to view and/or modify any part of
your file.

If you wish to exit from the editor, you can quit by typing a ’q’ followed by a car¬
riage return on the command line. If you try this later (after some text has been
entered), you may be greeted with a message indicating that you have changed
some text but have not saved it away. You can force an exit without saving your
text by typing a carriage return to clear the error and a ’qq’ followed by a carriage
return. We mention quitting here to rescue those people who jump in and then get
called away before they can read the rest of the manual.

Now that we have our bearings, let’s look a little closer at these three areas.

ED 4

2.1.1 The Status Line

This line is composed of three parts.’ On the left "Last=0" indicates, that the last
line of your text is line 0. You therefore have an empty buffer (zero lines). Next
to this, the numbers in brackets "( 0 , 1 )" indicate the current position of the cursor in
die file. It is of the form (row, column). The row indicates your current line and
for all but an empty buffer it will range in value between 1 and Last. On attached
terminals you may find that the column number does not change.

Next on the line are your current editing options. A ’+’ after an option indicates
that the option is ON while a indicates that it is OFF. Some options which are
meant to catch your attention when ON will display a flashing V. These options.
may be turned on and off at the command line. Some of the options are also tied in
with function keys. They are toggled ON/OFF by the indicated key.

Briefly the options have the following meaning:

a - Anchor Alt-a

This option will be better,understood after reading the section, on pattern mat-
. ching. For now it is enough to know that die editor has the ability to search for
text strings and leave your cursor at the string matched. Should you specify,, a
search for the string "mouse" with this option ON (a+), your cursor will be
anchored to the start of the pattern matched (in this case ’nT). With (a-), the^
cursor would be positioned at the character after the matched string "mouse"
(in this case the character after the V).

b » Blank Alt-fo

When viewing a piece of text on the screen, lines appear to be padded with
blanks to the end of the screen. Since the editor reads files with variable sized
lines containing 0 (a line containing only a carriage return) to 256 characters,
you may wonder whether the blanks at the end of the line are REAL or not.
With (b-f), the editor will allow you to differentiate between real blanks by
displaying nulls (non-existent characters) as small centered dots.

c - Command Large PLUS key

This option indicates whether your active cursor is in the command area (c+)
or text area (c-).

d - Dual ■ Alt-d

This option, like option anchor (a), concerns pattern matching. If OFF (d-)
then a search for "mouse" would match the string "MOUSE", "MoUse",
MOUsE and so on in your text. If ON (d+), the pattern matcher differentiates
between upper and lower case.

EDS

f - Fill Alt-f

This option when ON (f+) will cause automatic filling of input lines at your
defined right margin. The default right margin is column 60. Should you at¬
tempt to enter a character in this column then any preceding characters of a
word will be moved to the next line. Using this option you may enter text
without ever having to type a carriage return to end each line. This is ex¬
tremely useful when entering documentation and letters.

i - Insert ins key

With (i+), all characters typed will be inserted before the character at the cur¬
rent cursor position.

j - Justify Alt-j

This option is used in conjunction with option Fill. When both option fill (f+)

and option justify (j-f-) are ON then when each line is filled it will also be
justified.

1 - Limit Alt-1

This option will flash (1+) when a tagged operation is being limited between a

left and right limit

m- Meta Alt-m

With (m+), meta characters are enabled during pattern matching. A meta
character is a character which has special significance to the pattern matcher.
For instance the character dot (.) is a meta character that will match ANY
character, not just a dot. This option will be explained in greater detail later.

n - Newline FI or F2 keys

Whenever a carriage return is entered in the text area while this option is on, a
new line will open up after your current line to allow you to type in new text.
This can be thought of as line insert mode and is similar to character insert
mode (i).

s - Save Alt-s

With (s+), your buffer will be automatically saved in die file "autosave" after
every 20 Ikes of kput. While writkg to the disk you may still contkue to
type up to 256 characters per fine, however, your keys will not be echoed
(shown on the screen) until the write is complete.

t - Tabs . Alt-t

This option is similar to option blank (b). Tab characters k your text are ex¬
panded kto enough spaces to reach the next tab stop. What may appear as 4
spaces may only be one Teal* character. Tumkg this option ON (t+) will
display die actual tab character as a right triangle. With (b+) also on, the

spaces which pad the tab to the next tab stop will be displayed as centered dots

ED 6

since they do not exist within the buffer. Tabs are characters which are
heavily used within € programs for indentation.

w- Wrap Alt-w

This option allows pattern searches to wrap around from bottom to top or top
to bottom when ON (w+). If OFF then pattern matching will stop when it
reaches the last or first line of the buffer.

2.1.2 The Command Line

As previously stated, this line is used for entering text to be interpreted by the
editor as commands. If you have just entered the editor you should have a flashing
cursor (underline character) on the left margin of your command line. There will
also be an inactive cursor (rectangular block) in the text area. Whenever you type
a character (excluding cursor and most function keys) it will appear where the
active (flashing) cursor is, and the cursor will move to the right.

Now try to enter a few commands to change your options. Most options are
enabled by typing

o<option character>+

and disabled by typing

o<option character>-

First let’s turn on option blank by typing the string "ob+" followed by a carriage
return (don’t enter the double quotes). You can turn it off by typing "ob-<CR>"
where <CR> designates a carriage return. Finally, you can toggle it by typing
"ob~<CR>". A toggle causes the option to change state. If it was previously OFF
it will be turned ON and if it was previously ON it will be turned OFF.

Should you make a typing error you may delete characters by pressing the dark
grey back-arrow key or may delete the entire line by pressing the Ctrl and X key
simultaneously. Both of these keys work on the line containing the active cursor
and are similar to the line editing keys of the command interpreter explained in the
QNX Operating System manual.

If you type in an unknown command or do something which causes an error, an
error message will be displayed on the command line and held until you type a
carriage return to clear it. Try typing in "abc<CR>" to generate an error, then clear
it by typing a carriage return.

ED 7

You should NOTE that you may execute any system command while in the editor
by preceding it with an exclamation mark (!). For example

!ls

led anotherfile

The second example will invoke another copy of the editor. When you leave you
will return to this editing session,

2.1.3 Text Area

It is this area where your text is displayed and may be directly edited. As you have
seen by setting ’ob+\ the text area is currently empty. We are now going to enter
some text and follow through some examples to illustrate the function of the
various cursor and function keys. Option blank should be ON for these exercises

(b+>.

2.2 Appending New Text (FI key)

To enter toe text area wito toe intention or appending new text, you suouiu. press
the FI key. The cursor in the text area will become active (flashing) and the com¬
mand line will be cross-hatched. You will also see option newline enabled (n+)
and your last and current line on the line will now be (1,1) not (0,1). The dark back
arrow key and Ctrl X keys behave in the same manner as they did on the control
line.

Type in the following text, typing carriage return at the end of each line. We
apologize to J. R. Tolkien for the misquote.

Three Rings for the Eleven-kings under the sky,

Nine for Mortal Men doomed to die,

One for the Dark Lord on his light throne
In the Land of Mordor where the shadows lie.

In the Land of Mordor where the shadows lie.

After you finish typing you will want to turn off the option newline (n-). This can
be done by simply pressing the FI key again. FI is a toggle key. Note that option
newline is disabled (n-) and the cursor is positioned at the current line or the last
line typed. Please refer to Section 2.7 if you wish to leave the editor and/or save
your text.

ED 8

FI appends after the current line and F2 inserts before the current line. Now that
you have some text, let’s experiment with the cursor keys. Using the four arrow
keys at the right, you can move the cursor anywhere on your text (note: If the
arrow keys generate numbers, type the Scroll Lock key). Your screen will scroll if
necessary. You can move off the right of the screen until your status display in¬
dicates that you are on column 512. Note that you can’t move above the first line,
below the last line or to left of the first character.

Using the arrow keys, position yourself on line 2 directly under the "N" of "Nine".
Press the F2 key and note that option newline is now on (n+). A new line has
opened up between line 1 and line 2 and the cursor points at the beginning of this
new line. Press F2 again and notice how the line will disappear if you decide that
this is not the place where you want to insert a new line. Press F2 again and type
in the following:

Seven for the Dwarf-lords in their halls of stone,

Now press F2 again to turn off option newline (n-) and use the cursors to position
yourself on line 5 under the "I” of "In". Type FI (n+) to append lines after line 5
and type in the following 2 lines:

One Ring to rule them ail, One Ring to find them,

One Disk to bring them all and in the darkness bind them

Now type FI to turn off option newline (n-). The FI and F2 keys behave iden¬
tically when leaving newline mode.

2.4 Using the Del and Back-arrow keys

Position yourself about 10 spaces to the right of the word "throne" and type a let¬
ter. The editor will immediately lengthen your line with blanks so it can place
your character where requested. You can delete these blanks to restore the text by
pressing the back-arrow key or positioning yourself just past the "e" of "throne"
and holding down the Del key. The Del key deletes the character at the cursor
causing the line to shift over.

In general, you will find the back-arrow key useful for correcting new text being
entered, while the Del key is useful for editing existing text. As an added advan¬
tage, the Del key saves each character it deletes. Position yourself at the start of a
line and hold down the Del key. To restore the last deleted characters press the
Ctrl and the Ins keys simultaneously. By holding this key down you can restore
the last 256 characters deleted in this editor session. The characters need not be
restored where they were deleted. They will be restored at the active cursor

wherever it is, even at the command line. This can be a useful method of moving
strings of characters.

Change the word "Eleven" to "Elven" in line 1 by moving the cursor to the second
"e" and pressing the Del key. Now move to line 7 and position the cursor under the
"D" in the word "Disk" and change this word to "Ring" by simply typing over it.

Note that by default, you are always in replace mode.

2.5 Inserting text using the Ins key

Now that we can enter new text, replace existing characters, delete characters and
re-insert deleted characters, it would be nice to complete our capabilities by inser¬
ting new characters.

Move to the word "light" in line 4 and position the cursor under the "1". Change
this word to "dark" by pressing the Del key 5 times, pressing Ins (i+), typing the
word "dark" and then pressing the Ins key again to disable insert mode (1-).

2.6 Other Cursor keys which Simplify Editing

There are several more cursor keys which will simplify movement through your
text as follows:

1. Pressing shift and left tab H ~, will move the cursor to the start of the current line.

2. Pressing the Ctrl and the right tab will move the cursor to the end of the ^
current line. Always press the shift or Ctrl key-first before the appropriate or
K “. The key by itself is actually the tab key and will place a tab character in
your text. Tab characters inserted accidentally in your text can be deleted with
the Del key.

3. A Ctrl and either the left or right arrow cursor movement keys will step over
words quickly. They will always stop at the end of a line containing text. The
keys are symmetrical. If you overshoot, simply go in the opposite direction.

4. ' A Ctrl and either the up or down arrow cursor movement keys will move your
cursor up or down four lines.

To test the other cursor keys, a file exceeding the text area must be used. The file
/expl/inform (shipped with the QNX operating system on your boot disk) may be
used as a source of text for exercise two.

ED 10

2.7 Saving your Text

At any time you may leave the text area and go to the command area by typing the
large PLUS (+) key on the right hand side of the keyboard. Note that the right and
left cursor keys, the Del and Ins key will operate on the command line. Other
cursor keys refer only to the text area. Write your file away by typing:

w llenarae<CR> - Note that <CR> is the
carriage return key.

Do not type <CR>.

Filename is any valid pathname as explained in the operating system manual. After
your file has been saved, the editor positions you back in the text area where you
left off. You can now continue with the rest of the exercises or may leave the editor
by typing the Large PLUS (+) key again followed by a ’q’. If you modify the file,
the ’q’ command will not let you quit without saving your changes. If you do not
wish to save your changes type ’qq’ to force the editor to exit.

2.8 Exercise 2

Position the active cursor at the command line using the Large PLUS (+) key and
enter the command:

e /expl/inform

The V command deletes your current buffer and reads the file into the editor
creating a new buffer. Note that the editor checks to make sure any current file
you are working on has been saved before proceeding. If you get a warning, type
carriage return to clear the error and use the ’ee’ command to force the editor to
load the new file.

ee /expl/inform

Your buffer now contains too many lines to display on your screen and some lines
which are too wide to display in their entirety. You have a window of n lines by m
characters into your text. Try using your arrow keys to move about the current
screen. If you attempt to leave the screen it will automatically scroll. If you want
to move faster remember the Ctrl arrow keys step over words and the Shift and
Ctrl “* move to the beginning and end of a line.

Two common reference points in a file are its beginning and end. Press the Home
key and you will find yourself back at the first line. Press the End key and you will
find yourself at the last line of your buffer. A Ctrl and the Home or End key will
move you to the first or last line of your current screen respectively. This means
that you have a local Home and End as well as a global Home and End.

ED 11

To step through the file a page at a time you can use the PgUp and PgDn keys.
These keys lock up at the beginning or end of your file buffer. The cursor will be
left at your defined center line which defaults to line 3. If you prefer it to be the
first line or another line you can change it by entering command mode (the big V
key) and typing the view center command: eg "vc <number>" where number is
between 1 and (screen length - 2)

To set the defined center line to line 1 enter:

vcl

Occasionally you would like to scroll the screen up or down one line without
moving the cursor from its current screen line position. This can be accomplished
via the Ctrl-PgUp and Ctrl-PgDn keys.

When editing programs, one of the greatest virtues of a screen editor is its ability to
give you context via its full screen display. The unmarked 5 key on the numeric
keypad is designed to aid you in this respect. If you move the cursor to any line on
the screen then press the 5 key (termed the center key), your screen will be

redisplayed with that line positioned at your defined center line. Try positioning

the cursor on one of the lines at the bottom of the screen and press the 5 key.

We have now exhausted the supplied cursor movement keys and it is time to ex¬
amine the 10 function keys in more detail. QNX Software Systems has found that
the odd function keys are in general easier to type and where possible has placed
the more commonly used editing keys on them.

2.9 More on the FI and F2 keys

The FI and F2 keys as we have seen toggle the new line mode. While in newline
mode, you may at any time go to the command area and execute any editor com¬
mand or toggle any of the options. This includes setting option newline OFF in¬
stead of using the FI or F2 keys as toggle switches. This method of entering new
lines is different from most editors and much more flexible. You are not locked
into an append-only mode.

For example, if you are entering text with option blank off and want to know
where all your ’’real" blanks are, you can zip up to the command area, turn ON
option blank (b+) and zip back without leaving the newline mode. This facility
allows you to write your file occasionally without exiting from newline mode. The
editor always places you where you left off after your file has been written away.

Also, suppose you have 5 lines of text in your buffer and are half way through
adding line 6 when you notice a typing error on line 2. You are free to move im¬
mediately to line 2 using the cursor movement keys, correct the error, and return
again to where you left off on line 6.

ED 12

In an earlier example (Section 23) you inserted a line using the F2 key and turned
the newline mode off. You then moved the cursor keys to another position and
appended 2 lines using the FI key. As you will see from the following examples it
was not necessary to turn the newline mode off between the two steps. Newline
mode has no effect until you type a carriage return.

Try double spacing the first few lines of the /expl/inform file. Move to the first
line of the file by pressing the Home key. Press FI and type a carriage return and
then move to the start of die second line using the cursor movement keys. Type
another carriage return and continue appending a few blank lines in this manner.

You could also try the following:

1. Appending and inserting text lines in the file.

2. Correcting and inserting characters in the text using the Del and Ins key.

3. Combining steps 2 and 3 without leaving newline mode.

When leaving the newline mode using either the FI or F2 keys, the editor will
delete the last blank line. Typically when appending text users will enter their last
line followed by a carriage return. This will open up an unwanted hole which the
closing FI (or F2) conveniently removes. However, for your protection this
automatic delete is conditional upon the line being empty.

2.10 Deleting Lines (F3 key)

Your file now has a few blank lines which you may wish to delete. F3 is the line
delete key and will delete the current line. Move the cursor to the start of a blank
line and press F3. Continue deleting the blank lines in this manner. Now move to
a line containing text and press F3. If you wish very hard and then press Ctrl F2
your line will reappear.

The editor stores deleted lines in a delete buffer. The Ctrl FI will append the last
deleted single line after the current line and the Ctrl F2 will insert the line before
the current line. In this case, we inserted the deleted line because the current
cursor line moved down one line when the F3 key was used.

If you delete 5 lines you can restore them one by one using Ctrl FI or F2. They can
be deleted in one text area and "undeleted" into another area. In most cases, this
can be used as a method of moving lines of text; however, a simpler method of
. moving blocks of lines using the F7 and F8 keys will be explained later.

ED 13

2.11 Filling Lines (F4 key)

When in option fill (f+) your lines will be broken on word boundaries based upon
your current right margin. If at some time in the future you would like to change *
your right margin and refill your text you can accomplish this using the F4 func¬
tion key. It will take the line your cursor is on and all following lines up to:

1. A blank line which is assumed to be a paragraph separator.

2. The end of the file,
whichever occurs first.

A line may be marked as a paragraph start by typing an Alt-p. A paragraph symbol
will appear at the END of the line. The Alt-p acts as a toggle allowing you to
mark/unmark a line. Filling will stop at each paragraph start, that line will be
indented and filling will then continue until one of the above two conditions is
reached. The paragraph start is provided as a means to stop filling between two
consecutive lines.

If a group of lines have been tagged as described under the F7 key, then only those

tagged lines will be filled. Filling will step over each paragraph stop as described

above.

Lines are filled between your LEFT and RIGHT margins. If option justify (toggle
with Alt-j) is ON (j+), then the text will also be right justified.

2.12 Centering Lines (Ctrl-F4 key)

This key will center the current line between the LEFT and RIGHT margins. Mul¬
tiple lines may be centered by tagging them as described under the F7 key.

2.13 Splitting and Joining Lines (F5/F6 keys)

Sooner or later you are going to want to split a long line or join two short lines
together. The F5 key will split a line at the current cursor position into two lines.
The F6 key will join the cursor line and the following line together. In practice,
you normally split a line on a space and no longer want the space after the split.

The F5 key checks if the character under the cursor is a space and if so, deletes it
before the split. On a join, F6 checks to see if the cursor line ends in a space and, if
not, appends one before joining.

If you wish to keep a space on a split or suppress the append of a space on a join,
then use a Ctrl F5 or a Ctrl F6. These keys make no assumptions; they simply split
and join. Note that the operations of split and join are symmetrical. Try splitting
and joining several lines to get used to this function.

ED 14

2.14 Tagging Blocks of Text (F7/F8 keys)

It is often convenient to tag a group of lines, then select an operation to perform on
the lines selected. For example, earlier we mentioned a method of deleting a group
of lines. Although there are several ways of accomplishing this, the most con¬
venient way is by a tagged delete. The lines to be deleted are tagged and then
deleted as a group.

There are two types of tagging.

1. Line tagging

2„ Block (line and column) tagging,,

2.14.1 Line Tagging

This is the simpler form and allows you to tag lines in their entirety. The selected
operation applies to the whole line. For example, to delete a block of lines you
would locate the first line in the series to be deleted and press the F7 key. The line
is displayed in reverse-video to indicate that it has been tagged. F7 is another
toggle key which sets/removes a tag, hence the line could be "untagged" by pres¬
sing F7 again. This is a more complex toggle which is also tied into block tagging,
and you should pause about one second before depressing the key again to untag a
line.

Now move the cursor and tag the last line to be deleted using F7. You will notice
that all of the lines to be deleted in between the tagged lines now show up as
inverse-video. When you set two tags, aU lines between the two tagged lines are
treated as a tagged block. To perform the actual delete, press the F8 key (the tag
operation key). This key will prompt you for a command and typing a "d" will
delete all the lines as a block. The deleted lines can be restored as a block using
the Ctrl FI or Ctrl F2 (probably a Ctrl F2 since you would want to insert them
before the current line).

You will find that if you delete lines one at a time the editor will restore them one
at a time and if you delete them as a block they will be restored as a block. This is
explained in detail in the Reference Manual.

The tagging of lines may also be used as a method for moving and copying blocks
of lines. The F8 key has five functions:

■ d (delete, already explained)

- m (move)

- k (kopy)

ED 15

- s (save)

- p (print lines on $lpt)

To try the move option, find a small block of text and tag the first and last lines
using the F7 key. Move the cursor to another place in the text, press F8 and re¬
spond to the prompt with an’m’. The tagged block of text will be appended after
the current cursor line.

The kopy option is analogous to the move option. Tag a block of lines using the

F7 keys. Move to the desired location, press F8, enter a ’k’ when prompted and
the lines will be copied after the current cursor line. The original tagged block of
text remains unchanged.

The save option will save the tagged lines into the file Vtmp /group.member 9 ,
where GROUP and MEMBER will be numbers. The saved text may be restored
later using the SHIFT F8 key. Selecting a line paste (1) will insert the text before
the line your cursor is on. You may save and restore text between different edit
sessions and/or consoles.

The F4 (fill) and Ctrl-F4 (center) keys will operate on tagged lines if any have been
set. If not they default to the range indicated on the section describing them.

Some things to remember when using tags:

1. You are allowed a maximum of two tags at any one time. If you set a third tag,
then it replaces an existing tag.

2. Tag operations apply to all lines between two tagged lines. If only one tag is
set, a tag operation will apply to that line only.

3. The order in which the tags are set does not matter.

4. Tags may be removed from your text by:

(i) performing a tag operation function,

(ii) using the F7 key as a toggle switch, or

(iii) typing a Ctrl F7 which removes/resets all tags.

2.14.2 Block Tagging

Line tagging is sufficient for most editing tasks. It falls short in those cases where
you wish to operate on a block of text within a line. This occurs most frequently in
the preparation of multi-column text.

ED 16

For example, if you wished to move the block of C’s

AAAAAAA

DDDDDDD

BBBBBBB

CCCCCCC

UNDER the block of B’s you would need to tag only the C’s, not the A’s and B’s.
Enter the text above and position yourself on the first character of the first line of
C’s. Depress the F7 (tag key) twice in rapid succession. The first depression will
tag the line and the second depression will turn on the block tag feature and set a
left limit at your cursor. The characters from the first C to the end of your line will
be displayed in inverse video.

Now move your cursor to the C in the lower right comer and depress the F7 key
again. You need only depress it once. This will tag the last line of C’s and set a
right limit. The block of C’s should now be displayed in inverse video. If you
wish, you may adjust the line range being tagged or the limits of the tag by moving
your cursor and typing the F7 key. Unlike line tagging, typing F7 again will not
remove a block tag.

Now move your cursor under the first B on the line containing the first row of D’s
and depress the F8 key. You will be queried with a more extensive list of opera¬
tions then a simple line delete. They are

d - delete

The tagged block will be deleted. Any text to the right will slide over to the
left to fill the gap.

e - erase

Th e tagged block will be replaced by blanks. In the special case where there is
' no text to the right of the block then the text is simply deleted. This option
will maintain column integrity.

k - kopy

The tagged block win be copied to the current cursor location. The original

text is unchanged unless the destination overlaps the tagged block.

m - move and erase

ED 17

This is a combined KOPY followed by an ERASE.

M - move and delete

This is a combined KOPY followed by a DELETE,
s- save

The save option will save the tagged text into the file Vtmp /group.member’,
where group and member will be numbers. The saved text may be restored
later using the SHIFT F8 key. Selecting a column paste will insert the text at
your cursor. You may save and restore text between different edit sessions.

p - print

Print tagged block on the printer ($lpt).

Select the’m’ or "M" operation to move the block.

2.14.3 Insert Mode and Block Move and Copy

When performing a tagged block MOVE or COPY with option insert off (i-), the
moved text will simply overiay any cxi&iing lCal. u upiioii Hioci t is encioleci. ly-r j
then the text will be inserted before the cursor. This can add considerable con¬
venience. For example you may move the block of C’s in front of the block of D’s
by tagging it, enabling option insert, and performing a move to the first character
of the first line of D’s. You should tag extra spaces to the right so the columns line
up. After the move, delete the extra block of C’s. It is recommended that you
always check the state of option insert when performing a tagged block move.

2.14.4 Re-setting the Last Tagged Lines or Block

The Ctrl-F7 is a toggle which can be used to retag lines or a block. Depressing it
with NO tags set will restore the last tags set. Depressing it with tags set will clear
all tags.

Tags are set on absolute line and column numbers and inserting or deleting lines
and characters may cause your tags to move with respect to your text.

2.15 Re-executing Commands (F9/F10 keys)

These two keys are used for re-executing command line commands. The F9 key
will re-execute the last command. F10 will redisplay the last command allowing
you to edit it, if needed, before typing a carriage return to execute it. These func¬
tions will be more useful as you leam more editor commands in the next sections.

ED 18

2.16 Zooming Your Text

If you have an EGA card and have mounted the EGA library

mount lib /config/glib.ega Must be executed before

mounting my consoles

your console will support 25 by 80 text and 43 by 80 text. Typing Alt z will zoom

your display between these two modes. It is possible for custom screen drivers to
be written which support more than two screen sizes. In this case the editor is
capable of supporting up to 6 different screen sizes.

When the editor exits it will return your screen to the size it had upon entry. Note
that outside the editor the STTY command may be used to set your screen size.

stty rows=43
stty rows=25

2.17 Tabs

The editor has tab stops set every four columns with the first tab set on column
five. Typing the tab key will enter a tab character at your active cursor. When
displayed on your screen the tab character will be expanded into the necessary
number of spaces to move to the next tab stop. Try inserting a few tabs into your
text. You can display the tab character as a right triangle by turning on option tabs
(ot+). By also turning on option blank (ob+), padding spaces will be displayed as
small centered dots since they do not exist within your text.

Tabs are not treated with any special significance internally. They only affect your
display and cursor movement on the display. You can not position your cursor on
the padding spaces following a tab, only on the tab character itself or the first real
character following it.

The use of tabs rather than spaces for indentation in structured languages can save
considerable typing and file space storage on your diskette.

You can change your tab settings by using the View Tab command. On the com¬
mand line type:

vt2 • Tabs every 2

vt4 • Tabs every 4

vt8 • Tabs every 8

ED 19

2.18 Composed Characters

You may enter composed characters directly into your text. These are discussed in
the QNX manual in the section on terminal handling. For example, typing:

Alt (release the key) e 9 produces an e accent aigu
Alt (release the key) p i produces the symbol pi
etc...

2.19 Line Drawing Characters

You can redefine the Ctrl and Alt cursor keys into line drawing characters by ex¬
ecuting a macro file as follows.

x /cmds/box.macros Enter this within ED on the command line

R y perimep f by typ inc ^2,eh cursor -key and Alt cirrsor~lcey within the editor

The Home, PgUp, PgDn, End and 5 key should also be used. Some of the keys will
move you in the most natural direction for drawing a box, however, the Ctrl down
arrow will not move beyond the last line of your file buffer. You can press car¬
riage return to open up room.

2.20 Margins

The editor maintains a left margin which determines the point a carriage return will
return to and a right margin which determines the point at which filling will occur.

2.20.1 Moving Your Margins (Shift FI to F6)

A Shift FI will set your left margin at your current cursor position and a Shift F2
will set your right margin at your current cursor position. Shift F3 and F4 will
march your left margin left or right while a Shift F5 and F6 will march your right
margin left or right.

2.20.2 Auto Fill and Your Right Margin

Go to the command area (using the Large (+) key) and enable option fill with the
command

of+

or toggle it on with the Alt-f key combination. In the text area, append the fol-

ED 20

lowing ten lines (taken from "The Princess Bride" - William Goldman) as one long
line. Do NOT type a carriage return.

The year Buttercup was born, the most beautiful
woman in the world was a French scullery maid named
Annette. Annette worked in Paris for the Duke and
Duchess de Guiche, and it did not escape the Duke’s
notice that someone extraordinary was polishing the
pewter. The Duke’s notice did not escape the notice of
the Duchess either, who was not very beautiful and not
very rich, but plenty smart. The Duchess set about
studying Annette and shortly found her adversary’s
tragic flaw. Chocolate.

You will find that the editor will automatically take any partially typed word and
move it to the next line when the cursor column exceeds 60, which is your default
right margin. This feature allows you to type continuously without having to
closely watch the screen. You can change your right margin using the VIEW
command which will be described shortly.

2.20.3 Auto Justify

Go to the command area and enable option justify with the command

oj+

or toggle it on with the Alt-j key combination. In the text area, append the fol¬
lowing lines.

Prince Humperdinck was shaped like a barrel. His chest was
a great barrel chest, his thighs mighty barrel thighs. He
was not tall but he weighed close to 250 pounds, brick hard.

He walked like a crab, side to side, and probably if he had
wanted to be a ballet dancer, he would have been doomed to
a miserable life of endless frustration.

You will find that the editor automatically justifies each line with your right
margin when it fills. This option is only active when option fill is enabled.

A Ctrl-b will begin an indent of four spaces (increase your left margin by four) and
a Ctrl-e will end an indent (decrease your left margin by four). Append die fol¬
lowing 6 lines, holding down the Ctrl and typing a ’b’ or ’e’ for <Ctrl-b> and

ED 21

<ctrl-e>.

The year Buttercup turned ten,

<Ctrl-b>the most beautiful woman lived in Bengal,
<Ctrl-b>the daughter of a successful tea merchant.
This girl’s name was Aluthra,

<ctrl-e>and her skin was of a dusky perfection
<Ctrl-e>unseen in India for eighty years.

You should note that your left margin only determines the point you will return to
on a carriage return. You may use your cursor keys to move to the left of an in¬
dent.

Programmers should NOT use this feature for indentation. The TAB key should
be used instead. The above technique results in large quantities of spaces in your
files. This will result in larger files and slower compiles.

2.21 Line Flags

2.21.1 Overstrike Flag (Alt-o)

This will flag the end of the current line with a left arrow character. When this line
is written, the record separator will be replaced by a carriage return. As a result,
when this line is printed, no linefeed will be issued and the following line will
over strike this line. This flag is automatically set when reading source lines which
terminate in carriage returns rather than record separators. This allows reading and
editing the output of DOC files which have underlining and/or boldfacing.

2.21.2 Continuation Flag (Alt-c)

This will flag the end of the current line with a bidirectional arrow character.

When this line is written, the record separator will be suppressed. As a result, the
next line will be continued (joined) with this one. When the editor reads a line of
greater than 512 characters it will automatically split the input line and set this flag
on the split line. This allows for the editing of files containing very long lines.

2.21.3 Paragraph Flag (Alt-p)

This will flag the end of the current line with a paragraph symbol. This is used by
the fill key (F4).

ED 22

2.22 Some Simple Editor Commands.

You should now be able to create new files, edit existing files (e filename) and
write them away (w filename). Up until now you have had little reason to leave
text mode to go to command mode to execute editor commands. The next sections
will introduce you to some useful editor commands.

2.23 Learn Mode

If you have a sequence of keys which you enter often, you may wish to leam them
once and assign them to a single key. Let’s assume that you wish to leam the
string "Copyright © 1983". The next time you are about to enter it, type a ’Ctrl
Minus’ sign on the keypad and enter a ’Ctrl a’ when prompted for the key to leam.
Type in your text then signal the end of leam mode by typing a ’Ctrl Break’. From
this point on each time you enter a ’Ctrl a’ it will be replaced by the learned input
sequence.

It is possible to leam very long and complex sequences consisting of text, cursor
movements and commands.

2.24 Absolute Line Positioning

The Home, End, PgUp and PgDn keys allow you a coarse means of moving
through a buffer, however, if you want to be in the middle of a thousand line buffer
they are very awkward to use. If you go to the command line and type in the
number of the line you want to go to (followed by a carriage return to execute) the
editor takes this as a command to move your cursor to that line. This gives you the
ability to move through the file in absolute terms. For example, if a compiler is¬
sues an error for line 458 of a source file then upon reading that source file with the
editor you can go right to that line.

2.25 Simple Pattern Matching

When editing a file, you often want to be able to say "Find me an occurrence of
this string" so you can work on it without knowing precisely where it is. This is
especially tme when working from a paper listing in which you know the text
string you want to edit, but probably not its line number. In the editor you can find
a string simply by enclosing it in slashes on the command line. The command

/son/

will cause a search to be made for the string "son". If option dual is off (od-) then
the matching will be case insensitive and /son/ will match "SON", "SoN", "sON"
and so on. It will also match a line containing "personal" since it contains an in¬
stance of "son".

ED 23

Searching begins at the character AFTER your cursor, resulting in the editor fin¬
ding the next occurrence of your pattern. If the editor searches down to the end of
the buffer without finding your pattern and option wrap is ON (w+) it will continue
the search at the first line of the buffer and continue until it reaches and tries your
current line from behind. If your pattern is not found, an error will be generated.

Assuming you match a line containing your pattern, then that line will become
your current line and your cursor will either point to the first character of the string
matched (a+) or the character after this string (a-). The default is option anchor
enabled (a+); however, if you are adding commas to the end of words you may
prefer to switch to a-.

Enclosing a pattern in question marks instead of slashes will cause a search to be
made backwards through your buffer. Therefore

?son?

will search for the first occurrence of the string "son" starting at the character
before the cursor. If the editor searches backward to the beginning of the buffer
without finding the pattern and option wrap is ON (w+) it will continue searching
backwards from the end of the buffer. Again if your pattern is not found an error
will be generated.

The editor is careful always to remember the last pattern you specified. Typing

will cause a search for the last pattern specified. This can save typing when
looking for multiple occurrences of a long pattern. An even faster method would
be to use the F9 key to re-execute the last command.

Up until now we have used the words string and pattern interchangeably. Although
the editor can search for simple strings of characters like

/The quick brown fox/

they are a subset of a more powerful pattern matching facility. This facility is
enabled by the option metacharacters (om+) when you define a pattern. When
enabled the characters., @, $, A , *,/, ?, and [ have a special meaning. For in¬
stance, a Y is a pattern which matches any character. The pattern

/ax/

would match an occurrence of a string containing an ’a’ followed by ANY
character followed by a ’c\ The meanings of these characters are explained in

ED 24

detail in the reference manual (section 3). Unless you intend to read this you

should turn off option metacharacters (om-) or prefix all special characters with a
backslash character in your pattern. When prefixed by a backslash the special
characters mentioned above lose their special meaning. A

/catU

will only match the string "cat.” regardless of the state of option m. If you want to
match a backslash you must type two of them. A

/a\\b/

will match the string "aNb". For non-alphanumerics the rule is simply this. If a
character is preceded by a ’Y then remove the backslash and take that character
literally. This allows you to specify a slash in your pattern. A

/totalVnumber/

will match the string ,, total/number ,, . The slash is protected and not taken as the
pattern delimeter.

For alphanumerics the rule is slightly more involved. If the two characters fol¬
lowing the backslash are hexadecimal (0 to 9 or A to F) then the whole sequence is
taken as one character which has the hexadecimal value indicated. A

A§7/

is a pattern consisting of the single character whose hexadecimal value is 07. AAz/
is just a V while a Abe/ is the character whose hexadecimal value is be. If this
seems complex or confusing you probably don’t need this ability. Just remember to
type two back slashes to get one and that you can match a slash (or a ? if you scan
backwards) by prefixing it with a backslash.

2.26 File I/O Commands

As we have already seen, we can read a file into the editors buffer with the ’e’

command

e filename

ee filename

and write out our buffer to a file with the ’w’ command,
w filename

ED 25

Whenever you read a file with the edit command (e) three things actually occur.

1. Your current buffer is purged. However, your delete buffer is kept, allowing
you to delete from one file and undelete into another.

2. The filename you specified is memorized.

3. The contents of the file are read into your empty buffer.

In each example we have specified the filename that the command should operate
upon. This is not always necessary. Should you omit the filename it will default to
the filename of the last file you specified with your V command. Therefore...

e report

followed by a

will have the write command write to the file "report”. Likewise, an
e

will simply re-read the last file edited. This is often used when you bungle some¬
thing and want a fresh copy. Note that in this case you will probably have to issue

command to indicate that your unsaved buffer should be overwritten. For your
protection a simple V will not destroy an unsaved buffer.

If you want to check the name of your current file, you can issue the file command.

which will display it in the command area. You can change it (or define it) by
following the command with a filename.

f filel

This will define your current filename as "filel".

ED 26

It is often useful to read another file into a non-empty buffer after some specified
line. This can be accomplished with the Y command.

r fiie2 - reads file2 into the buffer after

tlie current line

The command may be prefixed by a number (or pattern search) to explicitly in¬
dicate a particular line.

lOr filename - reads file2 after the 10th line
in the text buffer.

/end/r filename - reads flle2 after the line

containing the next occurrence
of "end" in the text buffer.

The read (Y) command does not affect the current filename. If you do not specify
a filename after Y the editor will read another copy of the current file into your
text buffer.

It is also possible to prefix the write ( ? w s ) command with a line number or range of
lines to write.

w filename
33w filename
l,10w filename
#w filename

all lines are written
line 33 only is written
lines 1,10 are written
all tagged lines are written

Finally, you can append to a file by specifying the write append command which is
of the same form as the write command.

wa filename

This is useful when you wish to build a new file based upon lines or blocks of lines
from your current file (or many files).

l,4w file
24,30wa file
#wa file
e newfile
l,10wa file

initialize file with lines 1 through 4
append lines 24 through 30
append a group of tagged lines
read a new file
append first 10 lines

ID 27

2.27 The View Command

Users with a colour display can change the colour of the three display areas using
the view attribute command.

va <area> <foreground colour> <background colour>

where: area -> 1 - Status line

2 - Command line

3 - Text lines

colour -> Number between 1 and 15 inclusive

The colour card has a design characteristic that causes interference (snow, blips
etc...) when you write to the screen memory. To avoid this it is necessary to wait
for the horizontal retrace signal before writing characters. This has the side affect
of slowing down display updates. A number of colour card look-alikes do not
suffer from this problem and full sp^od up dating Qf the display may b Q restored
with the stty command system command.

stty type=l - fast colour card

stty type=2 - slow colour card

Do not use these commands on a monochrome card. It is always type 3.

Users with the improved cards should place this command in their ’/config/sys.init’
file.

2.28 Executing System Commands

Any QNX command may be executed from within the editor by preceding it with
an exclamation mark (!). For example:

!ls

Ifrel junk
!ec test &
led anotherJFile
Hist this fiie &

After executing the QNX command, the editor will pause, waiting for the user to
type carriage-return before redisplaying the screen. If you type two exclamation
marks (!!) the screen clear and pause will be suppressed allowing you to invoke
commands via macros in a hidden manner.

ED 28

Note that Ctrl-Z is recognized within the editor and will bring up a new shell al¬
lowing you to execute multiple commands. To return to the editor type a Ctrl-D to
terminate the new shell.

2.29 Epilogue

At this point you should be able to perform most editing tasks. However, this
introduction has hit on only a few of the editor commands and interested users are
strongly urged to read the reference manual, especially if they are interested in
defining their own function key operations.

ED 29

ED 30

3. Using Ed on a Terminal

When ED is invoked on an attached terminal it opens a file called ’/con-
fig/tcap.dbase’. This file contains information entries for different types of ter¬
minals. The entry for each terminal contains the output escape sequences neces¬
sary to:

1. Move the cursor

2. Change the text attributes to

- inverse

- highlight

- underline

- blink

- colour

3. Clear

- the screen

- to end of line

- to end of screen

4. Draw lines and boxes

The entry also contains the input escape sequences sent by any special keys on the
terminal’s keyboard. These are typically function and arrow keys.

You may query the terminals in the database by typing the TCAP command

tcap list ’

and you may query your currently set terminal by typing

tcap query

If the query does not agree with your terminal type, you may change it by typing
tset terminal_name

where the terminal name must be one of those listed in the database. If your ter¬
minal is not in the database, you will have to read the documentation on TCAP for
defining a new terminal.

ED 31

3.2 Required Terminal Capabilities

Any terminal which is to be used with ED must support the following capabilities.

1. Direct Cursor Addressing

2 . Screen Clearing

3. Zero width escape sequences

The last point requires further explanation. On some terminals, an escape se¬
quence to turn on inverse video takes up a character position on the line. As a
result your standard 80 column line will be reduced to 78 columns (one character
to turn on, and one character to turn off) ED does will NOT work properly on this
type of primitive terminal. Escape sequences must NOT take any physical room
on the screen. Fortunately, nearly all terminals work this way.

Although not required, the following capabilities are recommended

1. Clear to end of line.

2„ Insert and delete line.

3. Inverse video (and to a lesser extent underline).

4. Up, down, left and right cursor keys.

The first two will speed up display updates while the third is necessary for
displaying tagged blocks of text. If your terminal supports Highlighting or under¬
line, but not inverse video, then ED will attempt to display tagged areas of text
using these capabilities. Without cursor keys, the editor may be painful to use.

You may wish to consider a truly QNX compatible terminal described later in this
section.

3.3 Screen Output

Ed will adjust its output to conform to your terminal’s screen size. Display updates
will be determined by the baud rate of your attached terminal. This will be con¬
siderably slower than running ED on the console. Non-ascii characters

control : hex 0 to IF
extended : hex 7E to FF

will be displayed as a question (?) mark. They are saved and manipulated as the
characters they really represent. It is only the display which prints them as ques-
tion marks.

ED 32

Note: on attached terminals, the column position is NOT updated as you move
your cursor. To force an update you must type the <SHOW> key, which on a PC
keyboard, is the center key on the numeric keypad

3.4 Keyboard Input

It is keyboard input which really differentiates using ED on the console from ED
on a terminal. The console keyboard is rich in both function and cursor keys.
Unfortunately, most terminals are rather limited in the special keys that they
provide. To overcome this it is often necessary to enter a two or three character
sequence to simulate a single console key. The terminal database defines keys
according to their function. For example, the large PLUS key on the console key¬
board is called the SELECT key. It is used by most applications to leave some
form of input mode and return back to a command state. This key is very seldom
found on a terminal, so a default two character sequence of an

ESC CR - select key input sequence

is mapped into the code returned by the console SELECT key on input. The fol¬
lowing table contains the default mapping supplied by TCAP for a terminal with
NO special keys what-so-ever. The multi-character input sequences will be
mapped into the single key codes returned by the console keyboard. Terminals
which do support special keys may override these default sequences to match those
generated by its keys.

ED 33

Up Arrow - Ctrl u
Down Arrow - Ctrl j or Linefeed
Left Arrow - Ctrl h or Backspace
Right Arrow - Ctrl r

Home - ESC h

End - ESC e

Page up - Ctrl a

Page down - Ctrl b

Insert - Ctrl n

Delete - Ctrl k

Rubout - Delete or Rubout
Erase line - Ctrl x

Select - ESC CR

Cancel - ESC -

Help ' - ESC ?

Show - ESC s

Tab - Ctrl i or Tab

Tab to begin - ESC TAB b
Tab to end - ESC TAB e

Alternate - ESC a

FI to F10 - ESC 1 to ESC 0

Fll to F20 - ESC ! to ESC )

NOTE: The following are the translations which are done for the
function keys:

TCAP entry Key value as seen by ED

FI toFlO = FI to F10

FI 1 to F20 = CNTLJP1 to CNTL_F10

Alternate FI toFlO = SHIFTJF1 to SHIFTJFIO

Alternate FlltoF20 = ALTJFl to ALTJF10

The ALTERNATE escape sequence may prefix any other escape sequence. It may
be used to generate the control Arrows, Page up/down, Home and End keys as well

as another 20 function keys. These correspond to the SHIFT and ALT function

keys on the keyboard.

ED 34

There is no provision for executing any of the ALT letter keys such as ALT-b to
turn on option blank. You will have to go to the command line and type the option
command directly.

ob+ or ob-

You may examine the input escape sequences in effect for your terminal by typing
leap keys

3.5 QNX Compatible Terminals

There are several terminals on the market which feature complete QNX com¬
patibility. They feature a PC keyboard which generates the same codes as the IBM
console, and a 25 line display with the full PC character set and QNX escape se¬
quences. Phone our Technical Support line for the current list of such terminals. A
special TCAP entry exists for this type of terminal.

tset qnxt

ED 35

ED 36

4. REFERENCE MANUAL

4.1 The Syntax of Editor Commands

An editor command is of the form:

<line range>C<argument>"

where: <line range> indicates which lines to operate on.

C is a single character indicating a command.

<argument> is command specific information.

4.1.1 Line Range

The line range specifies which lines the command should operate on. It can consist
of zero, one or two line addresses. If no range is specified then it will usually
default to the current line. The current line is the line your cursor is on in the text
area and will typically be updated by each command to reflect the last line it
operated on. Check the section on each command for the exact behavior. A <line
range> is of the form:

or <line>
or <Iinel>,<line2>
or <linel>;<iine2>
or *
or #

where: <Iine> is the address of a particular line in your
text buffer.

The first form in which NO line address is specified will cause the command to
choose a default line address. If not stated otherwise, the default will be the cur¬
rent line.

The second form indicates that the command is to operate on the specified line
only.

The third form indicates that the command should operate on the range of lines
specified.

ED 37

The fourth form is similar to the third form except that the current line is set to

<linel> upon encountering the

The fifth form is an abbreviation for "1,$" which indicates that die command
should be applied to all lines, '

The final form indicates that the command should operate on the tagged lines in
the buffer. Depending on the number of lines tagged this can result in two forms:

<line> - only one line tagged

or <linel>,<!ine2> - two lines tagged

The elements of a <line range> are line addresses <line> and are composed of:

<number> This is an ordinary line number referring to the <number>th line
of the buffer.

$ This special character refers to the last line of the buffer.

. This refers to the current line of the buffer.

@ This refers to the line occupying the currently defined center line.

& This refers to the top line of your currently displayed screen.

% This refers to the current line if you are in the text area and line

zero if you are on die command line. It is often used in macros by
the ZAP (z) command to operate on the command line.

/<pattern>/ This is the address of the line which contains an instance of the
specified pattern. The search for <pattem> will begin at the
character after the cursor and will continue to the end of the buf¬
fer. If no match has been found by that time, and option wrap is
ON (w+), the search will wrap around to the beginning of the
buffer and continue looking for <pattem> from line one. If no
match is found in the entire buffer then an error will be issued.

^ This line search sets the condition register TRUE if a match is
found and FALSE if a match is not found.

?<pattern>? This serves as the line address of the line which contains an in¬
stance of the specified pattern. The search for <pattem> will
begin at the character before the cursor and will go backwards •
through the buffer wrapping around from the first to last line if
necessary. If no match is found an error will be issued as above.

ED 38

This line search also sets the condition register to TRUE on a
match and FALSE on no match.

Each line address above may be combined with other line addresses using the V
and keys to form expressions. For example.

.-Sj.+S - will specify the five lines

before and after the current line.

&;.+23 - will specify all lines on the

current screen.

?begin?,/end/ - will specify all lines between the

lines containing the previous "begin”
and the next "end”.

If you specify a line address which is outside the buffer you will get an error and
die command will NOT be executed. The special character OR-BAR (!) can be
used to limit the preceding line addresses to lie within the buffer (between one and
$). This is very useful in defining macros. The T operator sets the condition
register FALSE if the line address falls outside the buffer and needs to be limited.
For example:

&;.+23| - is a safer form of the example

shown above.

4.1.2 Command Specification Character

Each major command consists of a single character which has been chosen to
reflect its nature. For example, the character’d’ was chosen for the delete com¬
mand and the character ’w’ was chosen for the write command. This character
must be in lower case.

If a command line is entered which contains a <line range> but no command

44 .

then the current line is set to the last line address specified. In this case the cursor
will move to line 44.

Some commands require extra information to specify their operation. For ex¬
ample, the MOVE (m) command requires the specification of the destination line
address:

Other commands like die ZAP (z) command represent a class of commands which
are specified by sub-command characters. For example:

zed

is a zap cursor delete command. The "cd" are subcommands of the zap command
and will not be interpreted as the major commands V and *d\ This form of sub¬
command is used by several editor major commands.

4.2 Placing Multiple Commands On A Line

The editor allows you to place more than one command on a line. Each command
on the line is executed sequentially from left to right. For example:

ob+ot+

will turn on option blank followed by option tab. The command:

l»4d$d

will delete lines one through four and then delete the last line. Note that the line
range only applies to the command that it immediately precedes. Should an error
occur on any command then execution will be halted and any following commands
will NOT be executed.

Some editor commands consume all characters until the end of the line collecting
their right argument. They must therefore be the last command on any line on
which they occur. For example

e filename

consumes all characters until the end of the line collecting the filename.

The Full Screen Editor treats a small number of characters as special in certain
situations. These characters are described in the following subsections. The only
character you can NOT save in your text is an ascii Null (hexadecimal value 00).

ED 40

43.1 The Newline Character (hexadecimal IE)

The newline character in QNX is a record separator (hexadecimal value IE).
Source files separate lines by a single newline character NOT a carriage return
and/or linefeed. On input, whenever you enter a carriage return (hexadecimal
value OD) it is mapped into a newline character.

When the editor reads a file it collects characters up until a newline, replaces the
newline with a null (hexadecimal value 00) and saves the collected characters as a
line in your buffer. The point to note is that the newline is NOT saved. It is
stripped on a read and added to the end of each line when the file is written.

In the definition of complex macros containing several lines, the lines may be
separated by either a carriage return OR a record separator. The supplied macro
file has adopted the convention of using the record separator.

43.2 The Null Character (hexadecimal 00)

The Null character (hex 00) is used internally by the editor to delimit strings. It is
therefore not possible to save this character in your buffer. Should you attempt to
enter this character, the line (text or command) will be truncated at that point.

4.3.3 The Meta Characters <5>$ A &.*[

When option meta-characters is ON (m+), then these characters have a very special
meaning when used within patterns (they are special only within patterns). The
period V for example will match ANY character, not just a period. The meaning
of these characters is explained in the section on pattern matching.

43.4 The Backslash Character \

The escape character on the command line is the backslash. When it precedes a
meta character in a pattern it causes that character to be taken literally. That
character loses any special significance it might have normally had.

Following a backslash by two hexadecimal characters in a pattern or translate

string results in a single character with the hexadecimal value specified. For ex¬
ample ME is the single character whose hexadecimal value is IE (a record se-
parator).

4.3.5 The Tab Character (hexadecimal 09)

When displayed on your screen this character will be expanded into the necessary
number of spaces to move to the next tab stop. Tab stops are fixed at every four
columns with the first stop set on column five. You can display tabs by turning
ON option tabs display (ot+).

ED 41

Tabs are not treated with any special significance internally. They only affect your
display and your cursor movement on the display. You can not position your
cursor on the expanded spaces following the tab, only the tab character itself or the
real character following it.

4.3.6 The Command Character (hexadecimal FF)

On input, the character with hexadecimal value FF will cause all characters up
until die next record separator (newline) to be collected (no echo) in a hidden
buffer, then executed as a command. Any current text on the command line is
NOT affected. This character is used heavily by the translate command when
defining macros for the various cursor and function command keys.

This character is only special on input. You can place a hexadecimal FF character
in your text by using the substitute command and a \ff escape.

s/CAff/ - replace C with the hexadecimal character FF

4.3.7 The Recall Character (hexadecimal FE)

On input, the character with hexadecimal value FE will recall to the command line
the last command typed. This character is used by the F9 and F10 function keys.

You can place this character in your text by using the substitute command as
above.

4.3.8 The Keyboard Input Character (hexadecimal FD)

When this character is encountered in a macro, the editor will accept a character
from the keyboard. If several characters occur in a row, a maximum of that
number of characters will be accepted. Entering a carriage return will always
terminate input (skipping any remaining FD’s) and the carriage return will be
discarded.

4.3.9 The Macro Disable Character (hexadecimal A3)

On input, the character with hexadecimal value A3 will prevent the next character
from being expanded should a translate be in effect for it. For example, the Home
key has a hexadecimal value of AO, but is translated on input into the three
character string:

If you would like to prevent this expansion (to enter the key’s value) then you

ED 42

should proceed it with the key on the numeric keypad which generates the code
for the Macro Disable character. You can of course enter the Macro Disable
character itself by typing the key twice.

An alternative method of entering a translated key value would use the compose
sequence described in the QNX manual for direct hexadecimal input.

The editor maintains a special register called the condition register which is set to
TRUE or FALSE by some of the editor commands. This register can be tested by
the BRANCH (b) command and the UNTIL (u) command to perform conditional
execution of editor commands. These commands are commonly used in macros.

4.5 Delete Buffers

The Editor maintains a buffer for deleted characters and another buffer for deleted
lines.

4.5.1 The Character Delete Buffer

The character delete buffer is arranged as a stack 256 characters long. Adding a
character to a full buffer will cause the oldest character to be lost. In this manner
the most recent 256 characters are kept.

The editor maintains primitive commands for:

- adding a character to the buffer,

- removing the last character which was added to the buffer.

- purging the buffer.

These primitives are provided by subcommands of the ZAP (z) command.

The saving of the last deleted character via the Del key is performed by a macro
which saves the character under the cursor in the character delete buffer before
deleting it. Likewise, the restoration of a deleted character via the Cntl-Ins key is
based upon a macro which inserts the last character placed in the delete buffer
before the current cursor position.

4.5.2 The Line Delete Buffer

The editor maintains another buffer in parallel with your text buffer called the line
delete buffer. This buffer has the same structure as your text buffer, however, it
can not be displayed or directly operated on by the editor’s many commands. Each
time you delete a line via the DELETE (d) command it is moved from your text

ED 43

buffer into your line delete buffer. You can restore deleted lines using the special
forms of the APPEND (a) and INSERT (i) commands which can move lines from
the delete buffer back to your text buffer.

The moving of lines between the two buffers is slightly more complicated than is
indicated above and is best explained by an example.

If you were to delete 5 lines, one at a time (say via the F3 key) it would be nice if
you could undelete them one at a time so that the last line deleted was the first line
restored. This is particularly nice when you delete one line too many and just want
to restore the last one, not all of them. Conversely, if you were to delete a group of
100 lines as a block (say via a tagged delete) you do not want to have to restore
them one at a time but want them restored as a block as well. The above two
scenarios describe, from a user’s point of view, the editor’s implementation of the
line delete buffer. Associated with the buffer is a flag which indicates whether the
buffer contains a series of single line deletes or one block delete. To avoid confu¬
sion, the editor will purge the line delete buffer before adding in the following
circumstances.

~ i on perrorm a single line cieiefc aoo. tne line ouner contains a oiock delete.

- You perform a block delete. A block delete always purges the line delete
buffer before adding the new block.

Put simply, if you delete lines one at a time, they are undeleted one at a time and if
you delete a block of lines they are undeleted as a block. Mixing blocks or types is
prevented by purging before adding, if necessary.

When working with a very large buffer it is possible for the editor to mn out of
memory. When this happens it will purge the delete buffer in an attempt to free up
some space. You will be warned of this by a message on the command line which
you must clear (like an error) by typing a carriage return. Deleting all lines in a
file, then attempting to edit another large file will often generate this message. In
this case you have all of the original file in memory in the line delete buffer and are
trying to read another large file into the text buffer. They may not both fit!

4.6 Break Handling

The editor will terminate any operation gracefully at the earliest possible moment
after the BREAK (Ctrl Scroll Lock) key is typed. As a result of the break, any
operation may be incomplete on the range of lines specified for a command,
however, no line will be left in a partially modified state. Should you break out of
an EDIT (e), READ (r), or WRITE (w) command you may only move a subset of
the lines into or out of your buffer to the specified file.

ED 44

After servicing the BREAK the editor will leave you in command state.

4.7 The Pattern Matcher

The editor has a very powerful pattern matching facility which will match the class
of patterns known as regular expressions. Patterns are used for line searches and
by the GLOBAL (g) and SUBSTITUTE (s) commands. It is the editor’s pattern
matching facility that gives it flexibility in writing powerful macros. For example,
the Ctrl left and right arrow keys are implemented by a pattern which searches for
the next or previous word in your text. We will attempt to describe the patterns
accepted by the editor in a very rigorous manner. It is assumed that option meta
characters is ON (m+) during the definition of your pattern. If it is OFF (m-) then
the editor will only recognize the class of patterns represented by (a) and (b)
below.

(a) The simplest pattern is a single character. Such a pattern matches the
given character in either upper or lower case, unless option dual is ON
(d+) to make the Pattern Matcher differentiate between cases.

(b) Patterns arranged adjacently form a single pattern. For example:

/afoc/

matches any string "abc".

(c) The character 5 A 9 specifies a pattern which matches the null string at the
beginning of the line. Thus a line search of:

/ A charm/

would match the string "charm" at the beginning of a line.

(d) The character ’$’ specifies a pattern which matches the null string at the
end of the line. Thus a line search of:

/charm$/

would match the string "charm" at the end of a line.

(e) The character V specifies a pattern which matches any character. Thus a
line search of:

/charm./

would match the string "charm" followed by any character on a line.

ED 45

(f) Any pattern followed by a defines a pattern which matches a string of

zero or more occurrences of that pattern. Thus:

lb*l

matches the strings "b", "bb", "bbb”, etc. In addition, since patterns
will match zero occurrences of a given pattern "Zb*/" will also match

The Pattern Matcher will match a construction with the longest
sequence matching the given pattern beginning in a given column; for
example, if a line contains the string "bbbbbb", ”/b*/" will match all six
b’s as a unit, not individually.

(g) The construction 5, @(<number>) ?5 is a pattern which matches the null

string immediately before the <number>th column on the line. Thus a
line search of:

@(10)charm

would match the string ’’charm" starting in character position ten on the
line.

If <number> is zero or the character V then this pattern will match the
null string before the current cursor position in the text area.

If <number> is the character Y then this pattern will match the null
string before the next TAB stop. This can be used to turn runs of spaces
into tabs. See the SUBSTITUTE command.

(h) The construction "^string^’]" matches any one character in string and
no other. Thus:

/[0123456789]/

is a pattern which will match a single digit. Characters in the square
brackets are taken literally, without their special meanings; thus:

will match the character Y and no other. A sequence of characters may
be specified by separating the lower and upper character by a dash (-).
For example:

/[a-zO-9]/

is a pattern which will match any letter or any digit. To match a you

ED 46

may protect it with the backslash (\) character.

(i) The construction ,, [ A <string>] H matches any one character that is NOT
in string. Thus:

/[ A 0-9 ]/

is a pattern which will match any character that is not a digit.

(j) A null pattern 5, // f? is equivalent to die pattern most recently specified
within the editor. This feature is convenient for searching through a file

for a particular string. For example, if you are looking for the string
"hello" you could specify:

/hello/

the first time and:

on subsequent searches. An even quicker method of performing this
task would use the F9 key to simply re-execute your line search.

(k) Any character preceded by the backslash character ’V loses its special
meaning. Thus:

A\\ A U $/

would match the string "\ A .$".

4*8 Some Pattern Examples

/hello/

/ A hello/

/hello$/

/ A hello$/

/ *$/

will match the string "hello" anywhere on a line,
will match the string "hello" at the start of a line,
will match the string "hello" at the end of a line,
will match a line containing ONLY the string "hello",
will match all trailing blanks (including zero) on a line.

ED 47

/**$/

/[0-9][0-9]*/

/[a-z_J[a-z_0-9]*/

/@ (10) [0-9]/

/ A $/

/ A *$/
/ A \[a-z][a-z]*/

will match all characters (including zero) on a line.

will match a number like "3", ”862”, etc.
will match an identifier in the language C.

- will match a digit in column ten.

will match an empty line.

will match a line containing only blanks.

will match a line starting with a period followed by a name
(such as a command in die text formatter).

4.9 Editor Commands

The following pages contain an alphabetical list of all editor commands.

ED 48

After Current Line

Syntax:

<line>a

<line>ad

Description:

The first two forms of this command turn ON option newline (n+) and open
up a newline after the current line. If the second form with <text> is specified then
that text will be placed at the start of the newly opened line, this form is often
used within a GLOBAL (g) command to append a string after a set of matched
lines. The blank between the ’a’ and <text> is required.

The third form appends the last deleted line (or range of lines) from the delete
buffer. Option newline is not affected.

The append command must be the last command on a line.

Current Line:

Set to the address of the new line opened up.

Condition Register:

Not affected.

ED 49

4.11 b - Branch

Syntax:

b<number>

b<number>t

b<number>f

This command allows you to branch over <number>-l command lines. The
first form branches unconditionally, the second form branches if the condition
register is TRUE and the third form branches if the condition register is FALSE.
The condition register is not affected by the branch. Branches are often used inside
macros defined by the TRANSLATE ™ command and make little sense when
executed directly.

If <number> is zero then the current command line is re-executed. If <number> is
one, then the rest of the current command line is skipped. If <number> is greater
than one, then <number>-I command lines will be read and discarded. A com¬
mand line is considered as a string of characters terminated by a record separator
ME).

The BRANCH command can not be used inside a GLOBAL (g) or UNTIL (u)
command.

Current Line:

Not affected.

Condition Register:

Not affected.

ED 50

4.12 c - Change Lines

Syntax:

dine range>c
cline range>c ctext>

Description:

This command deletes the specified range of lines from the text buffer and
places them in the line delete buffer. It then turns ON option newline (n+) and
opens up one line for input. If the second form with ctext> is specified then that
text will be placed at the start of the newly opened line.

The change command is functionally equivalent to a DELETE (d) command fol¬
lowed by an INSERT (i) command.

Current Line:

Set to the address of the new line opened up.

Condition Register:

Not affected.

ED 51

4.13 d - Delete Lines

dine range>d

This command deletes the specified range of lines from the text buffer and

places them in the delete buffer.

If the dine range> specifies more than one line to be deleted OR the delete buffer
contains a previous delete of a range of lines, then the delete buffer is purged
before appending the new lines.

If a delete of a single line is requested and the delete buffer is empty or contains
lines which have been deleted one by one, then this new line is inserted at the
beginning of the delete buffer.

Current Line*

Set to the address of the line after the last line deleted.

Condition Register:

Not affected.

ED 52

4.14 e - Edit a New File

Syntax:

e <filename>
ee

ee <filename>

Description:

This command deletes the contents of the current buffer (without placing the
lines in the delete buffer) and reads in the lines associated with the specified file.

Since the contents of the delete buffer are not affected, you can use it to move lines

from one file to another by performing a DELETE (d), EDITING (ee) a new file

and then undeleting the lines into the new file (AD command).

The first form reads from the currently defined filename while the second form
reads from the indicated filename and makes that the current filename. Both of
these will not destroy a non-empty buffer which has been modified. The last two
forms will edit regardless of the current state of the buffer.

The current filename can be queried or changed by the FILE (f) command.

The EDIT command must be the last command on a line.

The EDIT command can not be used inside a GLOBAL (g) or UNTIL (u) com¬
mand.

Current Line:

Set to the first line of the buffer.

Condition Register:

Not affected.

ED 53

4.15 f - File Query/Set
Syntax:

f <filename>

Description:

This command allows you to query or set your current filename which is used
by the EDIT (e), READ (r), WRITE (w) and EXECUTE (x) commands when you

omit their filename.

The first form of this command displays your current filename on the command
line and waits for you to clear it by typing the carriage return key.

The second form sets the current filename to be the filename specified.

The FILE command must be the last command on a line.

Current Line:

Not affected.

Condition Register:

Not affected.

ED 54

416 g - Global

Syntax:

dine range>g/<pattem>/<more editor commands>
cline range>g A /cpattem>/cmore editor commands>

Description:

The GLOBAL command checks each line in the indicated line range for the

presence of the indicated cpattemx The first form marks lines which contain the
pattern while the second form marks lines which DO NOT contain the cpattemx
The GLOBAL command then executes the following commands for each marked
line, with the current line set at the marked line before executing. If no line range
is specified then ALL lines are searched for the cpattemx For example:

g/ A Comment/d

would remove all lines containing the string "Comment" at the beginning of the
line. To print them before deleting use:

g/ A Comment/pd

To Change all occurrences of the string "minimum" to "maximum" and print the
changed lines, issue a:

g/minimum/s//maximum/p

To delete all lines which don’t end in the string ",c" issue a:
g A A.c$/d

To append the line "--" after each line in the buffer, issue a:

g/ A /a -

To reverse the order of lines in your buffer, issue a:
g/ A /.mO

Finally, to print the lines around each line containing the string "function", issue a:
g/function/.-5,.+5p

ED 55

Current Line:

When the GLOBAL command is finished, the current line has the value it
had after the last command executed during the GLOBAL operation.

Condition Register:

When the GLOBAL command is finished, the condition register has the value
it had after the last command executed during the GLOBAL operation.

ED 56

4.17 i - Insert Before Current Line

Syntax:

<line>i

<line>i <text> , :

<line>id

Description:

The first two forms of this command turn ON option newline (n+) and open
up a new line before the current line. If the second form with <text> is specified
then that text will be placed at the start of the newly opened line. This form is
often used within a GLOBAL (g) command to append a string before a set of mat¬
ched lines. The blank between the T and <text> is required.

The third form inserts the last deleted line (or range of lines) from the delete buf¬
fer. Option newline is not affected.

The insert command must be the last command on a line.

Current Line:

Set to the address of the new line opened up.

Condition Register:

Not affected.

ED 57

4.18 j - Join Two Lines
Syntax:

<line>j

This command joins the indicated line to the line following it. As an intere¬
sting example:

uflj

will attempt to join all lines in the file.

Current Line:

Set to <line>.

Condition Register*

tSf

Set if a join occurs. Will always be FALSE on last line.

ED 58

4.19 k - Kopy Lines

Syntax:

dine range>k<target lino

Description:

This command kopies the indicated range of lines to the line following the
specified ctarget lino. The ctarget line> may be zero to insert before line one but
the ctarget line> may NOT fall within the source cline range>. The source lines
specified by cline range> are left untouched in the buffer.

The ’k’ for copy was chosen since the letter ’c’ was already in use by the Line
Editor and it was felt that its function should be maintained in the Screen Editor for
consistency. It’s not that we kan’t spell.

Current Line:

Set to the first of the kopied lines.

Condition Register:

Not affected.

ED 59

4.20 1 - Learn

1 <character>

Description:

All input until a Ctrl-Break will be saved as a macro. From this point, each
occurrence of <character> will be replaced by the learned input stream. To leam a
key sequence for the FI key you would enter:

1 \81

Current Line:

Not affected

ED 60

4.21 m-Move Lines

Syntax:

<line range>m<target lino

Description:

This command moves the indicated range of lines from their current position
in the buffer to just after the specified ctarget line>. The ctarget hne> may be zero
to insert before line one but may not fall within the source <line rangex

Current Line:

Set to the first of the moved lines.

Condition Register:

Not affected.

ED 61

4.22 o - Option Query/Set

Syntax:

ocoption characterxoption modifier
where: <option character is a single letter

^ ..r. {a,b,c,d,e,f,i,j,l,m,n,s,t,w}.

coption modifier> is a V, 0 r ’?’

Description:

The OPTION command allows you to change or query your editing ontinnc
The option selected is specified by the <option character and the operation is

£S th£ i <?P? on modifier. A V will turn an option ON a P ’-’ will turn an
option OFF and a ~ will cause the option to toggle. A does not affect the

SZiS t‘S'm? v' 1 " re ie' r 7 RUE 7*' «*» <*. ON »d??LsE if

P e + ’ and ~ do not affect the condition register.

Current Line:

Not affected.

Condition Register:

Set TRUE or FALSE if coption modifier is a
Each option is briefly described in a subsection below.

4.2X1 oa - Option Anchor

Whenever a pattern search is made, the editor will leave your cursor at the start

’ WnT — ° f the pattem matched * Should vou specify a search for the string
mouse with a+ your cursor will be anchored to the’m’ in mouse With (a ) thp g

charaar, 0 atL the°’e‘; 0ned ^ CharaCter after * e matched strin 8 "mouse''(the

4 * 22.2 oh - Option Blank

iiHililsssssr

ED62

4.22.3 oc - Option Command

This option indicates whether your active cursor is in the command area (e+) or
text area (c-). It is often queried and set within macros. The FI, F2 and large
PLUS key are examples of macros which do this.

4.22.4 od - Option Dual

This option, like option anchor (oa) concerns pattern matching. If OFF (d-) then a
search for "mouse" would match the string "MOUSE", "MoUse", MOUsE and so
on in your text. With (d-f) the pattern matcher differentiates between upper and
lower case.

4.22.5 oe - Option Environment

This option is handled quite differently from the other options. It does not have an
ON or OFF state. Each time you specify an oe-f command, your current options
will be saved. They may be restored by an oe- command. The editor only main¬
tains a single level of environment stacking. Multiple oe-f- commands simply
overwrite previous saves and multiple oe- commands simple restore the last en¬
vironment saved by an oe-f. This command is useful within macros where it may
be necessary to temporarily change an option to perform a required function. Only
the current state (ON/OFF) off each option is saved.

4.22.6 of - Option Fill

This option when ON (f+) will cause automatic filling of input lines at your
defined right margin. The default right margin is column 60. Should you attempt to
enter a character in this column, then any preceding characters of a word will be
moved to the next line. Using this option you may enter text without having to type
a carriage return to end each line. This is extremely useful when entering documen¬
tation and letters.

4.22.7 oi - Option Insert

With (i-f), all characters typed will be inserted before the cursor.

4.22.8 oj - Option Justify

With (j+), all filled lines will also be justified at your right margin.

ED 63

4.22.9 ol - Option Limit

This option will flash (1+) when a limited tag has been set.

4.22.10 om - Option Meta Characters

With (m+), meta characters are enabled during pattern matching. The meta charac¬
ters "@$ A &*[." are explained in detail on the section describing the pattern mat¬
cher.

4.22.11 on - Option Newline

Whenever a carriage return is entered in the text area while this option is ON (n+),
a new line will open up after your current line to allow you to type in new text.

This can be thought of as line insert mode and is similar to character insert mode

(oi).

4.22.12 os - Option Autosave

With (s+), your buffer will be automatically saved in the file "autosave" after every
20 lines of input. While writing to the disk you may still continue to type up to
256 characters per line, however, your keys will not be echoed until the write is
complete.

4.22.13 ot - Option Tabs

This option is similar to option blank (b). Tab characters in your text are expanded
into enough spaces to reach the next tab stop. What may appear as 4 spaces may
only be one ’real’ character. Turning this option ON (t+) will display the actual
tab character as a right triangle. With (b+) also on, the spaces which pad the tab to
the next tab stop will be displayed as centered dots since they do not exist within
the buffer. Tabs are characters which are heavily used within C programs for
indentation.

4.22.14 ow - Option Wrap

With (w+) pattern searches will wrap around from top to bottom or bottom to top
in your buffer.

ED 64

4.23 p - Print Lines

Syntax:

<line range>p
dine range>P

Description:

This command clears your screen and prints the specified lines on your
screen. If the number of lines exceeds the size of your screen, the command will
pause until you type a character to continue. If the first form is used (small p), then
any non-printing characters (less than hex 20 and greater or equal to hex 80) will
be expanded into a^ sequence. This can be useful in finding out the hex values
of some of the Function and Cursor keys (proceed them with the on the keypad
to put them in your text). This command is nearly always used in conjunction with
the GLOBAL command. It allows you to display lines which are not adjacent in
your buffer. For example:

g/index/p

will print all lines on your screen that contain the string "index". You may not edit
the displayed lines using the cursor keys. The editor has temporarily dropped out
of full screen mode.

Current Line:

Set to the last line printed.

Condition Register:

Not affected.

ED 65

4.24 q - Quit (Leave the Editor)

Syntax:

Th * s , command terminates the current editing session. For your protection the
editor will not let you quit via a single ’q’ if your buffer has been modified since

f n m a w m n°n SaV t ed Y °^ Can f ? rce a quit without saving by using the second

within^GLOBAL tote™ nS ^^ C ° mmand ° naHne3ndmuStn0tbe

Current Line:

Not affected.

Condition Register:

Not affected.

ED 66

<line>r

This command reads in the contents of a file and appends it immediately
following the line <line>. If a <filename> is not given, the current file is used. If
<line> is omitted, it will append the file after the current line.

The READ command must be the last command on a line.

The READ command can not be used inside a GLOBAL (g) or UNTIL (u) com¬
mand.

Current Line:

Set to the address of the first line read from the file.

Condition Register:

Not affected.

4.26 s - Substitute Text

dine range>s<dl><pattem><dlxreplacement textxdl>

cline range>scnumberxdlxpattemxdlxreplacement textxdl>

Description •

This command replaces occurrences of cpattem> with the string emplace¬
ment text> in the line range specified. If no line address is specified, substitutions
are made on the current line. The pattern and replacement text are delimited by a
single character cdl>. It is general practice to use the T character for this purpose,
however, any other character not appearing in cpattem> or creplacement text>
may be used instead.

The first form replaces ALL occurrences of the given pattern on a line while the
second form only replaces the cnumber>th occurrence on the line.

The character has a special meaning (with option m+) when used in the re¬
placement text. It will be replaced by the text of the pattern matched. For example:

s/however/&,/

is equivalent to:

s/however/however,/

This can be extremely useful when matching complex patterns where you may not
know the exact text matched. The is NOT a special character in <pattem>, and
all the pattern matching meta characters are not special in emplacement text>.

The backslash V character may be used in the definition of <pattem> and cre¬
placement text> to escape the meta characters, and the delimiter character <dl>
so they lose their special meaning. For example:

s/myfile\*/Vyourflle\&/

will replace the string "myfile*" with 7yourfile&". You can also match and re¬
place your text with exact hexadecimal character values using a\hh sequence. One
common use is splitting a line by inserting a record separator character. The com¬
mand:

ED 68

s/and further more/&\!e/

W ill split the current line after the string "and further more". You can notmatch a
record separator character in you text buffer as they are not actually stored, but
stripped and added when you read and write your buffer to a file.

The substitute command is often used for making QNX command (ec) files. You
first create a file of pathnames using the "files" command.

files p=*.c -v >fiist - create a list of my C programs

You would then edit the file "flist" and perform the following substitutions to
create a command file to encrypt all your C programs.

*s/ A .*$/<&>&/ - duplicate names with redirection

*s/..$/.e/ - replace last .c with .e

*s/ A /crypt / - prefix the crypt command in front of

all filenames

You would now write the file, leave the editor and execute the file,
sh flist

The @™ construct can be used to turn runs of spaces into tabs

s/@(t)A01/ - mark tab stops with a Ctrl-a

s/ *\01/\09/ - replace runs of spaces ending

on a tab stop with a TAB

Current Line:

Set to the address of the last line of the specified range.

Condition Register:

Set TRUE if a successful substitution takes place, otherwise, it is set FALSE.

ED 69

4.27 t - Translate a Key on Input

Syntax:

t <character> <replacement text>
t <character>
t ? <character>

T <character> replacement text>
T <character>

T ? <character>

Description:

This command translates an input character into a string of characters. It is
possible™ 311 ' 1 whlch makes the macro definition of the function and cursor keys

TJe first form translates the indicated character <charactei> into the string of
characters emplacement text> whenever that character is typed. The second form
removes any translation m effect.

The third form will display the current translation of the indicated character on the
command line allowing you to modify it if desired.

TJe definition of <character> may be a '>hh sequence. If you wish to enter the
character to be translated directly (you may not know its hexadecimal value) you
should precede the character with the key on the numeric keypad. This suppre-
sses any translation currently in effect for the key. It is recommended that you
NOT translate the or V key. You should keep in mind that one level of backs¬
lash escapes is stopped off during the translate command. This unfortunately
means that if you wanted to match a backslash in a substitute command, you would
have to type four of them to get one.

t \84 \ffsA\\V?Ale
\ffsAV?Ale

You enter this
This would be saved for the
definition of F4. The
SUBSTITUTE command would
turn the \\ into a single \
when the macro was executed.

If you use the little Y command then-recursive definitions are allowed If
a capital 1 then a macro within a macro will not be expanded.

you use

ED 70

The special character \ff (see section on special characters) should be prefixed to

any translation that you wish executed as a command. It causes all characters up to
the next record separator Me to be collected (no echo) in a hidden buffer and then
executed as a command. Any current text on the command line is NOT affected.

This allows you to define command translations which are independent of where

your active cursor is. For example:

t \01 MT/procedureAle

would cause a Ctrl-a to be translated into a scan for the pattern /procedure/. Note
that the Me was necessary to force execution. Without it you would have to type
the carriage return key yourself at the keyboard. If we were to omit the \ff, then
the text would be entered at the active cursor which would probably be ok if you
were on the command line, but unpleasant if you were in the text area.

As a further example, to translate the FI key into the string "QNX Software

Systems" you would enter the command:

t \S1 QNX Software Systems

Note that we did not prefix the replacement text with a \ff, nor did we end it with a

Me. Anytime you now type an FI, the string "QNX Software Systems" will be
entered at the active cursor, exactly as if you had typed the characters on the key¬
board yourself.

Current Line:

Not affected.

Condition Register:

Not affected.

ED 71

4.28 u - Until

Syntax:

dine range>u<count> cmore editor commands>
cline range>u<condition> cmore editor commands>
cline range>u<count><condition> cmore editor commands>
cline range>u cmore editor commands>

where ccondition> is: t - TRUE

f - FALSE

Description:

This command is used to repeat a list of commands a number of times until a
given condition is satisfied. The list of commands may contain another UNTIL if
desired, however, it may NOT contain a BRANCH (b) command. The space be¬
tween the ccount> or ccondition> and cmore editor commands> is required.

The first form will repeat the list of commands ccounO times.

The second form will set the condition register to the opposite of ccondition> and
repeat the entire list of commands until the condition register matches ccondition>
AT THE END OF one of the repetitions of the command list.

The third form will set the condition register as in the second form but will repeat
the list until either ccount> is reached, or the condition register matches ccon-
dition>, whichever occurs first.

The final form will repeat forever, or until you type break (or an error occurs).

In all cases the UNTIL will terminate immediately if any command in the list
generates an error. In this case the condition register will be in the state it had
before the error. The ERROR will NOT be printed, but absorbed by the UNTIL
command. This allows you to prevent a command from issuing an error message
by preceding it with a "ul ". For example:

ul s/IBM/I.B.M/

will not generate an error if the substitute fails.

If both ccount> and ccondition> are omitted, then the UNTIL will repeat until an
error occurs or you type Ctrl-Break.

ED 72

Current Line:

When the UNTIL command is finished, the current line will have the value it
had after the last command executed during the UNTIL operation.

Condition Register:

When the UNTIL command is fmished, the condition register will have the
value it had after the last command executed during the UNTIL operation.

ED 73

4.29 v - View Screen Options
Syntax:

va<number> <number> <number>
vc

vc<number>

vl<quantity>

vr<quantity>

vs<quantity>

vt214!8

vznumber

Description:

This command allows you to change some of the parameters associated with
your screen. The parameter is specified by the character following the VIEW (v)
command. The condition register is not affected by this command.

Current Line:

Not affected.

Condition Register:

Not affected.

Each parameter is briefly described in a subsection below.

4.29.1 va - Attribute

This command allows you to change the attributes (colour) of the three regions of
your display. The first number must lie between 1 and 3 and indicates the region.

1 - Status line 2 - Command line 3 - Text lines

The second and third number select the foreground and background colour.

0 - Black 1 - Blue 2 - Green 3 - Cyan

4 - Red 5 - Magenta 6 - Yellow 7 - White

ED 74

Hie foreground colour will be intensified if values greater than 7 are used.

8 - Black 9 - Blue 10 - Green 11 - Cyan

12 - Red 13 - Magenta 14 - Yellow 15 - White

This command is ignored when used with the monochrome display. Users with a
colour display may wish to add this command to the end of the file
Vcmds/ed.macros ’.

4.29.2 vc - Center Line

When used without an argument (form 1 above) this causes your screen to be
redrawn with the line your cursor is on positioned at your defined center line. You
may redefine your center line by specifying a number (second form above) be¬
tween 1 and 23. The default macro file sets your center line at 3.

4.29.3 vf - Full Display of Text and Attributes

The editor keeps track of the attributes stored on each line. To increase the speed
of screen updates on the console, Ed will not update the attributes when it believes
they have not changed. Programs such as QSPELL which modify the screen at¬
tributes without the editors knowledge may result in permanent attributes which Ed
will not remove. The view full command will force Ed to always update the at¬
tributes as well as the text on your screen.

4.29.4 vl - Left Margin

This command defines your left margin. The term <quantity> may be a simple
number in which case your margin will be set to that value, or it may be a number
preceded by a V or in which case that value will be added or subtracted from
the current value. This lets you define absolute or relative changes to your mar¬
gin. For example:

vl+5

will increase your left margin by five and:

vlS

will define your left margin to be five. As a special case, a V will set your margin
to the column that your text cursor is currently on.

ED 75

Your left margin defines the point you will return to in your text whenever you
type a carriage return. The characters before your margin will be filled by blanks
unless you have changed your default fill character (see ZAP (z) command).

Your left margin is constrained to lie between 1 and your right margin.

4.29.5 vr - Right Margin

This command defines your right margin in the same manner as "vl" defined your
left margin. Your right margin defines the point at which filling (automatic
generation of a carriage return) will occur on text entry if you have option fill ON

(f+).

Your right margin is constrained to lie between your left margin and column 1000.

4.29.6 vs - Scroll Screen

This command causes your screen to be scrolled. If you specify a negative quan¬
tity then the scroll will be backward and if you specify a positive quantity then the
scroll will be forward. This command always causes an immediate refresh of your
screen. This allows you to look at snap shots of your screen during the execution
of an until (or any list of commands). The command:

u20's/*/+/

would only display the final version of the line you modified when the editor
finished execution. The command:

u20 s/ A /+/vsO

would give you a snap shot after each iteration of the substitute command.

4.29.7 vt - Set tab settings

You may set your tab stops at every 2,4 or 8 characters on the screen. The default
is 4.

4.29.8 vz - Zoom the size of your screen

When given without arguments this command will switch to the next hardware
supported screen size. If the number is given it will switch to

vzO - Size of screen upon entry.

vzl - Screen size 1 (25 by 80 on an EGA).

vz2 - Screen size 2 (43 by 80 on an EGA).

ED 76

vzX Hardware dependent.

4.30 w - Write Buffer to a File

Syntax:

<line range>w

<line rangowa

Description:

This command writes out the specified lines to a file. If a <filename> is not
given the current file is used. If the dine range> is omitted then ALL lines are
written.

The last two forms (wa) will append the specified lines to the end of the file.

If a <filename> is specified and the current filename is not defined, then the
specified <filename> will become the current filename. Note that <filename> can
of course be a device like 5 $ipt\

Current Line:

Set to the address of the first line written.

Condition Register:

Not affected.

ED 78

x <filename>

Description:

This command will open up a file and execute its contents as a series of
editor commands. If a <filename> is not given the current file is used.

This command is commonly used to load macros via a file of translates. The editor
does an EXECUTE on the file "/cmds/ed.macros H immediately after execution

begins. An execute file may NOT contain another execute.

The EXECUTE command can not be used inside a GLOBAL (g) or UNTIL (u)
command.

Current Line:

The current line is set by the commands in the execute file.

Condition Register:

The condition register is set by the commands in the execute file.

4.32 y - Yut?

Syntax:

dine range>y"<prompt text>"<command chars> M <arguments>

This command does not know what it is. It will print cprompt text> on the
command line then wait for you to type the letter of a command. If the character
you type matches the nth character of ccommand chars> then control will transfer
to the nth line. Each line is separated with a record separator (\1E).

y"k for kopy or m for move f, km f, \le\ff#k.b2\le\ff#m.\le

would prompt:

k for kopy or m for move

on the command line and pause for you to type a character. If you typed an’m’
then the command:

#m.

would be executed, which happens to be a tagged move to the current line.

If the typed character is not found, then the last command will be executed. The ’n’
command is an invalid command and can be used to generate errors on invalid
keys. In the following example, a space or any invalid key will generate an error:

y ,f k for kopy or m for move”km ,, \le\ff#k.b3\le\ff#m.b2\le\ffn\le

Current Line:

Set according to the command executed.

Condition Register:

Set according to the command executed.

ED 80

4.33 z - Zap
Syntax:

dine range>zccccharacter>

cline range>zcd

cline range>zcDclocation>

cline range>zceclocation>

cline range>zcfccharacter>

cline range>zchclocation>

cline range>zcl

cline range>zcp

cline range>zcr

cline range>zcRcnumber>

cline range>zcs

cline range>zh

cline range>zkcline>

cline range>zlc

cline range>zld

cline range>zle

cline range>zlf

cline range>zlj

cline rangozlo

cline range>zlp

cline range>zlq

cline range>zlr

cline range>zlR

cline range>zlR"filename"

cline range>zls

cline range>zlt

cline range>zlu

cline range>zlw

cline range>zlw"filename"

cline range>zmctext>

cline range>zp

cline range>zq#

cline range>zq!

cline range>zvcdigit>

Description:

This command consists of a number of useful subcommands which relate
directly to the capabilities of a full screen editor. The subgroup starting with ’zc’
(ZAP CURSOR) deal with the cursor and are further subdivided by a third
character to indicate a particular function. The cline range> for the "zc" group

ED 81

may be a single line address of zero in which case the command will be applied to
the command line instead of the text area. Each ZAP function is described in a
subsection below.

Current Line:

In all cases, it is set to the last line of the specified range, however, not all
ZAP commands use the line range information (zp for example).

4.33.1 zee - Zap Cursor Change

This function changes the character under the cursor to the character specified.

The <character> may NOT be a \hh escape sequence but may be a carriage return.

If option insert is ON (i+) then <character> is inserted BEFORE the cursor.

Condition Register:

Not affected.

d.H.7 wd - Zar> Cursor Delete

This function deletes the character under the cursor causing the rest of the line to
shift to the left.

Condition Register:

Trying to delete a non-existent character (you are to the right of the end of the
line) will set the condition register FALSE. A successful delete sets it TRUE.

4.33.3 zcD - Zap Cursor Delete Multiple

This function will delete all characters from the current cursor position to the posi¬
tion specified by <location>. The <location> is specified in the same manner as the
’zch’ command.

Condition Register:

Trying to delete a non-existent character (you are to the right of the end of the
line) will set the condition register FALSE. A successful delete sets it TRUE.

4.33.4 zee - Zap Cursor Erase

This function will erase all characters from the current cursor position to the posi¬
tion specified by clocationx This allows erase to end of field (right margin) to be
implemented via a

ED 82

zcer

The <location> is specified in the same manner as the ’zch’ command. If the field
does not end the line, the field is replaced with blanks instead of being deleted.
This preserves column integrity.

Condition Register:

Set TRUE if any characters are erased.

4.33.5 zcf - Zap Cursor Fill

This function defines the fill character to be used whenever you type a character to
the right of your text (indicated by a small centered dot in option blank (b+)). The
default is to extend the line with blanks. However it may be changed to any
character, a period being a typical example. The <character> may NOT be a\hh
escape sequence.

The fill character is often changed to a TAB when used in conjunction with the
Ctrl-b (begin indent) and Ctrl-e (end indent) keys when writing programs. Inden¬
ting by TABS rather than spaces is strongly recommended.

NOT affected.

4.33.6 zch - Zap Cursor Horizontal

This function moves the cursor horizontally on the line. The movement may be
absolute, relative or based upon a pattern. The field <location> determines the
type of movement and can be one of:

+<number>

-<eumber>

/pattern/

Absolute movement to indicated character cnumberx
Relative movement forward <number> characters.
Relative movement backward <number> characters.
Move to end of line.

Move to left margin.

Move to right margin.

Starting at the current cursor attempt to match
the indicated pattern. Note that the line is
assumed to start at the cursor and all characters
to the left of the cursor are ignored. The
pattern / A ./ would match the character at the
cursor NOT the beginning of the line. Option
anchor will determine the new location of the

ED 83

cursor on a match.

?pattern? Starting at the current cursor and scanning

BACKWARDS, attempt to match the indicated pattern.

Note that the line is assumed to start at the
cursor and extend backwards to the beginning of
the line. All characters to the right of the
cursor are ignored. Due to the backward scan, the
line will appear reversed to the pattern. To
match the string "IBM" you would specify the
pattern ?MBI?. This is only true of backward
searches using the ZCH command.

In all cases above, the cursor is limited to lie between index 1 and 512.

Condition Register:

An attempt to move the cursor outside the text on the line (or a pattern match
fail) will set the condition register FALSE, otherwise, it is set TRUE.

4.33.7 zcl - Zap Cursor Lock

When the editor is forced to move the cursor to a line which is not within the cur¬
rently displayed screen, it will by default redisplay with the cursor line positioned
at your defined center line (see vc<number>). The Zap Cursor Lock command,
LOCKS the cursor to the TOP or BOTTOM of the screen on a redisplay. Concep¬
tually, if your cursor must move off the top of your screen then, it will remain
locked at that position and your text will scroll down as required. Likewise, if your
cursor must move off the bottom of your screen, then it will remain locked at that
position and your text will scroll up as required.

As an example the UP ARROW and DOWN ARROW are implemented as:

.-ljzcl and .+l|zcl

to prevent a re-centering of your display when your cursor attempts to leave the
screen.

Condition Register:

NOT affected.

ED 84

4.33.8 zcp - Zap Cursor Purge

This command purges all characters in the character delete buffer.

Condition Register:

NOT affected.

4.33.9 zcr - Zap Cursor Restore

This command causes the last character put in the delete buffer to be restored at the
current cursor position. If option insert is ON (i+) the character will be inserted
before the cursor.

Set TRUE if the character delete buffer contains at least one character to
restore.

4.33.10 zcR - Zap Cursor Restore Multiple

This command will restore the last <number> characters put in the delete buffer at
the current cursor position. If option insert is ON (o+) the characters will be in¬
serted before the cursor.

Condition Register:

NOT affected.

4.33.11 zcs - Zap Cursor Save

If the cursor is positioned on a character, then it is saved in the character delete
buffer. If the cursor is not on a character (off to the right of the line) then nothing
is saved.

The character delete buffer may hold a maximum of 256 characters. Saving more
than this number causes any new character to be inserted at the front and the oldest
character is lost. Only the last 256 characters are kept.

Set TRUE if a character is saved.

ED 85

4.33.12 zh - Zap Home

This command will move your cursor to the top left hand comer of a tagged block
of text. For example, say you wish to write a macro which saves a tagged block of
text to a file, executes the SORT command and replaces the tagged tagged text
when sorted. It is necessary to ensure that the cursor is positioned at the top left
comer of the text when you read the file back in.

t\01 \ffzh\le\ffzp#zlw u tmp M ! Isort tmp +r\le\ffzpzlR M tmp'\le

Condition Register:

NOT affected.

4.33.13 zk - Zap Kopy

This command provides a convenient method of kopying a text line to the com¬
mand line and vise versa. A line address of zero designates the command line. For
example

Ozk. - kopy command line to current line

.zkO ■ kopy current line to command line

Condition Register:

Not affected.

4.33.14 zlc - Zap Line Center

This command will center the text between the left and right margins of the in¬
dicated lines.

Condition Register:

NOT affected.

4.33.15 zld - Zap Line Delete

This command will delete the text between the left and right margins of the in¬
dicated lines.

ED 86

Condition Register:

NOT affected.

4.33.16 zle - Zap Line Erase

This command will erase the text between the left and right margins of the in¬
dicated lines.

Condition Register:

NOT affected.

4.33.17 zlf-Zap Line Fill

This command will fill the text between the left and right margins of the indicated
lines.

Condition Register:

NOT affected.

4.33.18 zlj - Zap Line Join

This command will set the join flag on the indicated lines.

Condition Register:

NOT affected.

4.33.19 zlo - Zap Line Overstrike

This command will set the overstrike flag on the indicated lines.

Condition Register:

NOT affected.

4.33.20 zip - Zap Line Paragraph

This command will set the paragraph flag on the indicated lines.

ED 87

Condition Register:

' NOT affected.

4.33.21 zlq - Zap Line Query

This command will set the condition code true if there are any marks set.

Condition Register:

TRUE if any marks set.

4.33.22 zlr - Zap Line Restore

This command will restore the contents of the delete buffer where the current text
cursor is. The delete buffer is not affected.

Condition Register:

NOT affected.

4.33.23 zlR - Zap Line Restore File

This command will read the contents of a file into the delete buffer then restore the
contents of the delete buffer where the current text cursor is. If no file name is
specified, then the file Vtmp/group.member’ will be used where group and member
are numbers.

Condition Register:

NOT affected.

4.33.24 zls - Zap Line Save

This command will save the text between the left and right limit at the end of the
delete buffer. Limits are set by tags.

Condition Register:

NOT affected.

ED 88

4.33.25 zlt - Zap Line Tag

This command TAGS the indicated line if it was untagged and UNTAGS it if it
was TAGGED. If there are already two tags in effect then this tag will replace one
of the tags. NOTE: If two ’zlt’s occur within 1/2 second then option limit will be
enabled and the line will not be untagged.

Condition Register:

NOT affected.

4.33.26 zlu - Zap Line Untag

This command removes all tags in the file if any are set or sets the last tags if there
are not any tags set. It is a toggle.

Condition Register:

NOT affected.

4.33.27 zlw - Zap Line Write

This command will save the text between the left and right limit at the end of the
delete buffer. Limits are set by tags. The data is then saved into a file. If no file
name is specified, then the file Vtmp/group.member’ will be used where group and
member are numbers.

Condition Register:

NOT affected.

4.33.28 zm - Zap Message

This command will print the message which follows on the command line. This is
useful as a prompt.

Condition Register:

NOT affected.

4.33.29 zp - Zap Purge

This command purges all lines in the line delete buffer.

ED 89

Condition Register:

NOT affected.

4.33.30 zq - Zap Query

This command sets the condition code based upon the character which follows the

zq.

Condition Register:

# - TRUE if any tags have been set
! - TRUE if zero exit status of last command

4.33.31 zv - Zap Version

This command sets the condition code based upon the version number of the
editor. The version is a number between 0 and 9. If the editors version is greater
than or equal to the digit specified the condition code will be set TRUE.

zvl Set condition code TRUE if editor version 1 or later

Condition Register:

TRUE if editor is greater than or equal to indicated version.

ED 90

This section is intended for the advanced user who wishes to add functions to the
supplied macro file "/cmds/ed.macros" or define a set of new macros for a par¬
ticular editing task at hand. Before trying your hand at new macros you should
have read both the Tutorial Guide and Reference Manual in detail. Macros are
basically very simple to write, BUT only if you have a good grasp of the many
editor commands described in the reference manual.

5.1 What is a Macro

A macro is just the simple replacement of an input key with a string of characters.
The replacement string contains the keys you would have to type to perform the
required function manually. As an example, let’s look at the definition of the Ins
key. Each time it is typed, it toggles option character insert (oi). You could per¬
form this task manually by going to the command line and typing the command

or*

which will toggle the option. You would then want to go back to the text area if
that’s where you came from. If you were already on the command line with a
partially typed command then the situation is slightly more complex. You can’t
type in a new command on the command line without deleting what is currently
there. To overcome this difficulty, the editor provides a very special character
called the ccommand char> which causes all input following it, up to the next
newline to be collected (without echo) in a hidden command buffer which is then
executed. By prefixing all commands with this character you can execute com¬
mands regardless of whether you are on the command line or in the text area. The
value of die command character is hexadecimal FF and may be entered directly
from your key board by holding down the Alt key and typing the backarrow key
normally used for character delete. You can now toggle insert mode at ANY time
by typing the string

ccommand char>oib<new!ine>

where ccommand char> is an Alt-backarrow and <newline> is either a carriage
return or a record separator (Ctrl A ). To turn this into a macro for the Ins key you
would translate the value generated by the Ins key into the above string.

Newline character.

Command character.

Hexadecimal value generated by
the Ins key.

ED 91

If you leave off the command char then the string

or*

followed by a newline would be entered at the active cursor. Likewise, if you

leave off the newline, then the command will be collected, but you will have to
supply the newline yourself by typing a carriage return.

Most macros are this simple. However, care should always be taken to ensure
reasonable behavior when a requested operation may fail. An example of this is
the down arrow key on the keypad. It is designed to move you down one line.

This could be performed by executing the command

.+1

which works fine until you try to move past the last line in your buffer where you
will be greeted by an unpleasant error message which will quickly annoy any user.
The simple solution is to limit the line address to remain within the buffer using the

T operator. The resulting macro definition would be:

\ff.+l|\le

which behaves in a friendlier fashion. As one final point, to prevent your screen
from being re-centered when you attempt to leave the screen, you might add a ZAP
CURSOR LOCK command resulting in

\ff.+l|zcl\le

Lets look at one more simple example illustrating the importance of planning your
macro’s behavior in all possible situations. You want the PgDn key to display the
next page of your buffer. Your text area is 23 lines so you might simply attempt to
move forward 23 lines via a

.+23

This has two problems

1. You may not have another 23 lines in the buffer.

2. If your current line was not on line 1, then you would miss part of the next
page. You should be jumping forward relative to the address of the top line of
the current screen. The PgDn is currently defined as

ED 92

t \aa \ff@+23I \le

Limit address to lie within buffer
Address of top line on the screen.
Hexadecimal value generated by the

PgDn key.

5.2 Multi-line Macros

Most of your macros will consist of one or more editor commands entered as a
string which makes up a single command line. There are cases, however, where
you will find that you need to enter a multi-line command. You may do this by
simply embedding <newline> characters in your translate string. The macro

t \84 \fful *s/register//\le

\fful *s/short/int/\le
Start of line two.
End of line one.
Start of line one.
Hexadecimal value
generated by F4 key.

defines a macro which will remove all occurrences of the string "register" and
change all occurrences of the string "short" to the string "int". The UNTIL one
(ul) will prevent an error from being printed if the substitute fails to find a match.
By placing them on two lines we are guaranteed to perform the second substitute
even if the first one fails. Remember, an error (even inside an UNTIL) terminates
execution of the current line.

5.3 Macros Containing Branches

The most common use of multi-line macros involves the BRANCH (b) command.
This command was included in the editor to allow you to perform conditional
execution of editor commands within macros. A simple example is the large
PLUS key on your keypad which performs one of two tasks. If you are in the text
area it simply places you on the command line. If, however, you are already on the
command line, it simulates your entering a carriage return to execute any com¬
mand, then places you back on the command line. Hitting carriage return would
normally execute any command then put you back in the text area.

ED 93

This key is defined as.

t \§7 \ffoc?b2f\le\

1 ©

Return to command mode.
Literal newline to execute

command line.

Query and set condition

This macro is interesting for two reasons.

1. It makes use of the BRANCH (b) command to conditionally execute editor
commands. If you are in the text area it will skip two <newline> characters
and only execute the "\ffoc+\le" which will place you in command mode.

2. It mixes literal text (which is entered at the current cursor) with command text
(which is preceded by a\ff and is collected in an execute buffer). If you were
already on the command line it will not branch, and therefore enter a <new-
line> on the command line which will cause it to be executed. You will then
fall into the code which sets option command and goes to the command line.

Defining complex macros which contain several branches and several lines quickly
becomes confusing when displayed as a single line with embedded <newline>
character escapes. The macro for the F2 key illustrates this.

t \82 \ffon?b3t\le\ffi\le\ffb4\le\ffon-zchl\le\ffb2t\le\ffd\le

This macro can be better understood when displayed as the multi-line sequence

t \82 \ffon?b3t

\ffi

\ffb4

\ffon-zchl

\ffb2t

\fffd

Check if option newline is on or off.

If it is off, then do an insert command
and skip the rest of the macro.

Else go to the beginning of the line and skip
to the end of the macro if line isn’t empty.
Delete the empty line.

It should be remembered that the zap cursor horizontal command (zch) will set the
condition register false if you move to a position which does not contain a charac¬
ter. If there is no character in the first column then the line must be empty.

There is a macro which will allow you to type in a macro in your text buffer in the
multi-line form above and convert it into a single string on the command line
which you may type carriage return to enter. This macro is defined in your

ED 94

"/cmds/ed.macros" file, but has been commented out by a double quote. You may
remove this quote and then execute the file

x /cmds/ed.macros

to define this macro as your Alt-m key. If you type the Alt-m key in the text area,
it will compress your buffer into a single line and move it to the command line for
execution. If you are on the command line, then it will take a macro which you
have displayed via the

I ? \fafa

command and place it in your text buffer in a multi-line format.

For interest this macro is defined as:

t \84 Woc?b7f*da
Won-om+Ozkl

\fful sA\\\\\\V\\80/

Wul sA\\\le/\\le/

Wul *sA\80A\\\\\\V
W0zce255 IzchlbS
Wom+

Wul *s/$A\\\le/

Wu40 Ij

WlzkOzchloc+

This macro uses UNTIL commands to prevent errors should a substitute fail.

In the case where you are on the command line, it deletes your buffer and places an
empty line in it via the APPEND command. It then copies the command line to the
empty line and splits the line at each\le. Note that it is not tricked by a\\le se¬
quence.

The reverse process appends each line with a Me sequence, joins all lines, then
copies it to the command line. It leaves the joined line in your text buffer allowing
you to save it with a write or write append command.

At this point you should examine the macros defined in the file "/cmds/ed.macros"
to gain further insight into the writing of new macros. You may examine them by
reading the file, or by displaying each key’s translation one at a time via the "t ?
\hh" command and then using the F4 key to show it as a nice multi-line sequence.
If you do not know the hexadecimal value of a key, then you may enter it’s literal
value by preceding it with the macro disable key (MINUS key on the keypad). For

- Start of code in the case
where you are in the text area.

ED 95

example, you could type either

t ?\§t
or

t 9 <MINUS keyxFl key>

The possibilities for macros are endless. QNX Software Systems encourages their
fullest possible use, but warns you that creating them is very much a black art...

ED 96

APPENDIX A - ERROR MESSAGES

The Full Screen Editor prints any errors it detects on the command line and pauses
for you to type a carriage return to clear the error.

out of memory

The Editor was unable to allocate space to replace an existing line or add a
new line.

unknown command

The editor encountered an unknown major command or subcommand
character.

invalid pattern specification

A pattern was specified which was not acceptable because:

- Terminating delimiter of pattern missing.

- Pattern exceeds 128 characters.

- Pattern starts with a

- // pattern specified when no pattern was defined.

buffer has been modified, use qq to quit without saving

An attempt to leave the editor via the quit command when your text buffer
has been modified since your last write to a file.

invalid line number or line range

A command has detected an invalid line number or range of line numbers.
This can be caused by:

- <linel>,<line2> where <linel> is greater than
<line2>.

- <line> is greater than the last line in the buffer.

- <line> is zero on a command other than a,k,m,r or z.

- Target of a move or kopy falls within the source
range.

ED 97

x command encountered within an execute file

An attempt has been made to nest execute commands.

current file not defined

An e,r,w or x command was entered without a filename and no current
filename was defined. You can define it with the f command.

unable to access file

The file system was unable to open the requested file. This can be caused

by:

- Invalid filename specified.

- No permissions to open file, (read, write or append)

- Filename specified can not be found. Check spelling.

syntax error

A. recognised command was specified incorrectly Some commands

which do not take a line range will flag a syntax error if given one (eg: e,

0 .

filename too long

A pathname of more than 64 characters was specified on a e,f,r,w or x
command.

unknown option

An unknown option character was specified in the option command.

line greater than 512 chars

On a read from a file, a line greater than 512 characters was encountered.
The line is broken at 512 characters. Reading will continue when you
type carriage return. The j and s commands can also cause this error.

ED 98

pattern not found

The pattern specified in a line search or a substitute command was not
found anywhere in the buffer.

disk error

An error has occurred while trying to read/write a disk file. Make sure that
the disk is not write protected (if writing). Otherwise, this error may
signal a defective diskette or a bad block.

Attempt to write to a file which is not the current file. Use ww

to force.

You are trying to write to a named file which is different from the one you
edited. Perhaps you wanted to type "e file" and missed the V and hit the
*w* instead. If you are sure, recall the line using the F10 key and insert a
second ’w’ for a command of "ww file".

ED 99

Page

1. Operating System Limits i

1.1 File System Limits \

1.2 Device Limits 1

1.3 Other Limits j

2. Floppy and Tape Backup for QNX 3

2.1 Introduction 3

2.2 Archive Structure 4

2.3 Backup Philosophy 4

2.4 Detailed Command Descriptions 5

2.4 .1 CONFIG - Configure the Tape Hardware g

2.4.2 INTT - Initalize NEW Archive 7

2.4.3 FILES - List Saved Files In the Archive g

2.4.4 SAVE - Save Files to the Archive 10

2.4.5 RESTORE - Restore Files from an Archive 15

2.4.6 VERIFY - Verify Data Saved to the Tape/Diskette 19

2.4.7 NAME - Print Volumn Name of an Archive 20

2.5 Examples 20

2.6 Saving Multiple Disk Paritions Per Archive 21

3. The QNX File Structure

3.1 BLOCK 1 - The ROOT Block

3.2 The BITMAP

3.3 Files

3.4 Extents 26

3.5 Directories 28

4. Recovering Files On a Disk 31

4.1 Utilities Provided 31

4.2 Recovering a Single File on the Disk 31

4.3 Recovering a Directory on the Disk 32

4.3.1 A Single Entry in a Directory Was Corrupted 33

4.3.2 An Entire Directory Was Corrupted 34

4.3.3 The Root of the File System Was Corrupted 34

4.3.3a Root Directory Uncorrupted 39

4.3.3b Root Directory Destroyed 39

4.4 The Structure Of A File 40

5. Page Caching Disk Drivers

1. Operating System Limits

This section describes limits of the QNX operating system at the time of printing.
Use the TSK command to verify what your version supports. For more informa¬
tion call our Technical Support line.

1.1 File System Limits

Max

These are the same for PGAT and ATP versions

number of extents per file:
bytes per extent:
files per directory:
blocks per disk:
disk volume size (bytes):
file size (bytes):
number open files:
number QNX drives:
number mounted drivers:
number adopted drives:
drives/nodes in search:
characters in filename:
characters in a pathname:

65,535

2,147,483,647

32,767

2,147,483,647

1,099,511,627,776

4 to 1000 (configurable). Default ->64.

256

1.2 Device Limits

PC AT ATE

PHYSICAL TTY’s (console): 1* 1*

(serial ports): 10 16

(parallel ports): 2 2

Additional ADOPTABLE TTY’s: 20 40

* Unused serial/parallel port device entries can be used to mount up to 7 extra consoles.

1.3 Other Limits

Tasks (combined virtual and local):
Ports:

Accounting Entries:

Registered Names (local):

Extra Segments (configurable):

Memory:

PCAT

ATP

150

100

160 -

160

to 200.

to 800

640K

640K Base
+ up to 15Meg

Extended

QNX 1

NOTE: Only one RAMDISK can be mounted.

QNX2

2. Floppy and Tape Backup for QNX

Please read this entire document before deciding on
an archive philosophy.

All examples using FBACKUP also apply to TBACKUP

2.1 Introduction

When saving large amounts of data to floppy diskette the QNX BACKUP com¬
mand poses several problems. It is relatively slow and no single file may be
greater than the size of the floppy. The solution to this is the FBACKUP and
TBACKUP commands which are very fast and allow files to span media boun¬
daries.

FBACKUP® Archive to floppy diskette or Bernoullie
removable hard disks.

TBACKUP® Archive to 1/4 inch tape cartridge using Everex,

Tecmar and Wangtek QIC60 internal/external tape units.

The set of floppy diskettes or tapes produced is called an archive and may only be
manipulated by the FBACKUP or TBACKUP commands. In other words, you
may not use LS, COPY,... on archive diskettes and tapes.

There are seven functions provided by the FBACKUP and TBACKUP commands.

config

init

files

name

save

restore

verify

® Configure the tape hardware. Used by TBACKUP only.
9 Initialize a floppy/tape for archiving.

® List files in an archive.

• Print the volume name of the archive.

® Disk to archive save.

® Archive to disk restore.

° Disk and archive compare.

Maintaining an archive system involves several phases, as follows.

Phase 1

Before you can use a diskette/tape for archive backup it must be initialized. This is
done using the the INIT function to the FBACKUP or TBACKUP command. Note
that only the first diskette/tape of an archive should be initialized.

QNX 3

Phase 2

Files can now be saved on the floppy/tape using the SAVE function. This function
supports a rich series of options similar to the QNX command called BACKUP.

Phase 3

After a SAVE you may wish to run a verify operation on the tape. This is op¬
tional. If performed, it should be run on a new tape.

Phase 4

In the event of a catastrophe, you may have to restore files saved in the archive
back to a disk using the RESTORE function. This may be needed in the case of a
hard disk malfunction, or in the case of a "boo-boo'\ such as accidentally releasing
a file.

2.2 Archive Structure

The first block of each archive diskette/tape contains the name of the archive and
the sequence number of this diskette/tape.

volume name I directory I file 1 I file 2

Diskette/tape 1 floppy only

volume name I continued data

In the case of FBACKUP the first floppy also contains a fixed length directory
which is created when the archive is initialized. The data is stored after this direc¬
tory. The floppy data portion of the diskettes are formatted without any sector
interleave. FBACKUP uses multi-sector I/O to maximize the data rate to and from
the diskettes.

2.3 Backup Philosophy

Using a file-by-file system, one backup technique available is called incremental
backup. In this technique, a backup of all files is performed periodically, and a
backup of the modified files is done more frequently. For example, a complete
backup of all files may be performed Monday evening at closing time. Then, on
Tuesday through Friday, only the modified files are saved into separate directories
on the archive. In the next week, the process is repeated with a DIFFERENT set of
archive diskettes. Depending on preferences, there may be four or five archives
being cycled in this fashion. If a complete restore is needed, restore from the last
complete backup, then restore from each of the partial backups taken since then. If
only one file is needed, look in the most recent partial backups first, and if it is not
found there, restore the file from the most recent complete backup.

QNX 4

Some computer centers also like to maintain archival copies of their files. In this
case, every fourth incremental archive, for example, could be filed away instead of
being cycled. Of course, it would have to be replaced with a new archive to enter
the cycle of incremental archives. In this way, a record of all files would be kept
for each month, approximately.

Although incremental backups are faster and smaller, they are more complex to
restore from. You have to determine the day on which the file was last saved.

This will be Monday and perhaps one or more weekdays. A full backup every day
eliminates searching for files on the archive, at the expense of using diskettes/tapes
and time.

Lastly, when backing up a large database, a single change to a record entails saving
away the complete file, which may be many megabytes. In this case, an in¬
cremental backup may not save any time since die large database files may change
(if even a little bit) every day.

2.4 Detailed Command Descriptions

Each of the five functions provided by the FBACKUP and TBACKUP commands
will be described separately. Typing

fbackup ?
or

tbackup?

will give you a usage message should you forget one of the option letters. Note that
only the first two letters of a FBACKUP/TBACKUP function need be entered.

QNX5

2.4.1 CONFIG - Configure the Tape Hardware

Syntax:

tbackup config c =dma__channel I =io_port u=aleli

where unit is: u=a • Archive Scorpion (internal or external).

u=e ® Everex/TecmarAVangtek external.
u=i • Everex/TecmarAVangtek internal.

Description:

To use the TBACKUP command you must first configure the TBACKUP com¬
mand to your hardware. This is done using the CONFIG function. This will create
a file called /config/tape.w where n will be replaced by your node number. This
will be zero in a non-networked system. For example, to configure an external
tape unit which uses ioport 338 and dma channel 3 you would type.

tbackup coring c=3 1=338 u=e typical AT setup

On a PC with a hard disk, dma channel 3 is already in use. You should set your
tape controller card to use use DMA channel 1.

tbackup config c=l i=338 u=e typical PC setup

QNX6

2.4.2 INIT - Initalize NEW Archive

Syntax:

fbackup [drive] init max-num-files ["v= volume-name ''] [^capacity]

[-format] [f =format_cmd]

tbackup init ["\=volume-name"]

The INit option will reformat the diskette/tape. In the case of a floppy archive
y°u m ust reserve room for a directory which can contain up to the number

StowIngSzes ^ MSp ” 8flopPy diske “ e “ d is “

Floppy Size
360K
720K
1.2Meg

Max Number of Files
2876 (c=360k)

5756 (c=720k)

9596 (c=1.2m)

The size of the archive may be selected to be one of three standards using the od-
tions provided. The 720K size requires an 80 track disk drive while the 1 2Meg
size requires a high capacity disk drive on an AT. You may of course create an
archive with a much smaller number of files in the directory. This will leave more
room for data on the first diskette.

TT WlU Suppre , ss the messa ge that this will destroy an existing
archive. It will also suppress the reformatting of the diskette. The t=format cmd

forn^^n e iOME^A e ca^dge. 0mman< ^ * f0imat ^ media ' ™ S i$ needed Fo

m format option^ 6 y ° U d ° n0t need t0 specify the director y size, tape size

raLFS onSn * e ar - hiVe ? V 0 , 1 T e name - The name will be displayed by the
,.S option. The name is optional, but is recommended so you can tell one ar-

an0tI T' Pi SA ,y E “ d RESTORE functions have anTption

%u ve™p"Zg. W V6nfy 111311116 V ° lumename of the arc hive is what

Mn U SA VF^y/ln 7 ° n th K firel flopp y /tape before you can use the archive. You

cm SAVE files any number of times to an existing archive. Until you re-create it

the new data is simply appended to the end of any existing data.

QNX-7

2.4.3 FILES - List Saved Files In the Archive

Syntax:

fbackup [drive] files [directory] [options]*
tbackup files [directory] [options]*

Internet Archive Audio

Featured

Top

Images

Featured

Top

Software

Featured

Top

Texts

Featured

Top

Video

Featured

Top

Mobile Apps

Browser Extensions

Archive-It Subscription

Save Page Now

Full text of "QNX 2.2 Reference Guide"

See other formats